Get customers

GET

customers

curl -X GET \
 /customers \
 --header "Authorization: Bearer <token>"

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "customerNumber": "CUSTOMER-000",
      "timeZone": "Europe/Berlin",
      "firstName": "John",
      "lastName": "Doe",
      "currencyCode": "EUR",
      "countryCode": "DE",
      "companyName": "Acme Inc.",
      "vatId": "DE123456789",
      "isVatIdValid": true,
      "datevId": "123456789",
      "commercialRegisterName": "Amtsgericht Berlin (Charlottenburg)",
      "commercialRegisterNumber": "HRB 123456",
      "status": "STATUS_ACTIVE",
      "gender": "male",
      "phone": "+49 123 456789",
      "language": "de",
      "totalTurnOverRank": 10,
      "createdAt": "2020-01-01T00:00:00+00:00",
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      },
      "businessCustomer": true,
      "defaultAddress": {
        "id": "<string>",
        "vatId": "DE123456789",
        "type": "TYPE_DEFAULT",
        "default": "true",
        "status": "active",
        "city": "Berlin",
        "zip": "12345",
        "street": "Musterstraße",
        "houseNumber": "1a",
        "countryCode": "DE",
        "companyName": "ACME Inc.",
        "salutation": "Herr",
        "addition": "c/o John Doe",
        "costCentre": "123456789",
        "firstName": "John",
        "lastName": "Doe"
      },
      "defaultInvoiceAddress": {
        "id": "<string>",
        "vatId": "DE123456789",
        "type": "TYPE_DEFAULT",
        "default": "true",
        "status": "active",
        "city": "Berlin",
        "zip": "12345",
        "street": "Musterstraße",
        "houseNumber": "1a",
        "countryCode": "DE",
        "companyName": "ACME Inc.",
        "salutation": "Herr",
        "addition": "c/o John Doe",
        "costCentre": "123456789",
        "firstName": "John",
        "lastName": "Doe"
      },
      "defaultEmailAddress": {
        "id": "00000000-0000-0000-0000-000000000000",
        "email": "john.doe@example.com",
        "receiverName": "John Doe",
        "type": "TYPE_COMPANY",
        "default": "true"
      },
      "defaultInvoiceEmailAddress": {
        "id": "00000000-0000-0000-0000-000000000000",
        "email": "john.doe@example.com",
        "receiverName": "John Doe",
        "type": "TYPE_COMPANY",
        "default": "true"
      },
      "defaultPaymentMethod": {},
      "isPartner": true
    }
  ],
  "meta": {
    "pagination": {
      "totalItems": 123,
      "itemsPerPage": 123,
      "currentPage": 123,
      "lastPage": 123,
      "pageTotalItems": 123
    }
  }
}

Authorizations

Authorization

string

header

required

Value for the Authorization header parameter.

Query Parameters

page

integer

default:1

The collection page number

limit

integer

default:30

The number of items per page

Required range: 0 <= x <= 100

partner

string

customerNumber

string

firstName

string

lastName

string

companyName

string

emailAddresses.email

string

vatId

string

datevId

string

isVatIdValid

boolean

isVatIdValid[]

boolean[]

customerGroup.name

string

Response

200

application/json

Customer collection

data

object[]

data.countryCode

string

required

Example:

"DE"

data.id

string

Example:

"00000000-0000-0000-0000-000000000000"

data.customerNumber

string

Required string length: 2 - 255

Example:

"CUSTOMER-000"

data.timeZone

string

default:Europe/Berlin

Example:

"Europe/Berlin"

data.firstName

string | null

Can be empty if the customer is a company.

Required string length: 2 - 255

Example:

"John"

data.lastName

string | null

Can be empty if the customer is a company.

Required string length: 2 - 255

Example:

"Doe"

data.currencyCode

string

Can be empty. In this case the default currency of the tenant is used.

Example:

"EUR"

data.companyName

string | null

Required string length: 2 - 255

Example:

"Acme Inc."

data.vatId

string | null

Required string length: 2 - 255

Example:

"DE123456789"

data.isVatIdValid

boolean

Indicates if the VAT ID is valid. This is only available for EU VAT IDs. We validate the VAT IDs each night and directly after change.

Example:

true

data.datevId

string | null

The ID of the customer in DATEV

Required string length: 2 - 255

Example:

"123456789"

data.commercialRegisterName

string | null

The name of the commercial register. This is needed tofullfill the collection processes on companies.

Example:

"Amtsgericht Berlin (Charlottenburg)"

data.commercialRegisterNumber

string | null

The ID of the customer in the commercial register, e.g. HRB 123456. This is needed tofullfill the collection processes on companies.

Example:

"HRB 123456"

data.status

enum<string>

default:STATUS_ACTIVE

Available options:

STATUS_ACTIVE,

STATUS_ARCHIVED,

STATUS_SUSPENDED

Example:

"STATUS_ACTIVE"

data.gender

enum<string>

This field is needed, to fullfill a collection process on a personal customer.

Available options:

male,

female,

diverse

Example:

"male"

data.phone

string | null

Required string length: 2 - 255

Example:

"+49 123 456789"

data.language

enum<string>

default:de

The language of the customer. This is used for the communication with the customer or on generating documents like invoices, reminders, etc.

Available options:

de,

en

Example:

"de"

data.totalTurnOverRank

integer | null

The current customer rank, based on their revenue. Lower is better. This will calculate each night.

Example:

10

data.createdAt

string

Example:

"2020-01-01T00:00:00+00:00"

data.customFields

object | null

Custom fields for the entity. The keys are the field names and the values are the field values. They need to be configured under "/custom-fields" in the API documentation. The input is validated against the configuration. For more details see Custom Fields Guide

Example:

{ "field1": "value1", "field2": "value2" }

data.businessCustomer

boolean

data.defaultAddress

object | null

The default address of the customer. This is the address that is used for billing if no other address is specified.

data.defaultInvoiceAddress

object | null

The invoice address of the customer. This is the address that is used for billing if defined. If not defined, the default address is used.

data.defaultEmailAddress

object | null

The default email address of the customer. This is the email address that is used for billing if no other email address is specified.

data.defaultInvoiceEmailAddress

object | null

The invoice email address of the customer. This is the email address that is used for billing if defined. If not defined, the default email address is used.

data.defaultPaymentMethod

object | null

The default payment method of the customer. This is the payment method that is used for billing.

data.isPartner

boolean

Indicates if the customer is a partner.

meta

object

Get series data for subscription Create customer

curl -X GET \
 /customers \
 --header "Authorization: Bearer <token>"

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "customerNumber": "CUSTOMER-000",
      "timeZone": "Europe/Berlin",
      "firstName": "John",
      "lastName": "Doe",
      "currencyCode": "EUR",
      "countryCode": "DE",
      "companyName": "Acme Inc.",
      "vatId": "DE123456789",
      "isVatIdValid": true,
      "datevId": "123456789",
      "commercialRegisterName": "Amtsgericht Berlin (Charlottenburg)",
      "commercialRegisterNumber": "HRB 123456",
      "status": "STATUS_ACTIVE",
      "gender": "male",
      "phone": "+49 123 456789",
      "language": "de",
      "totalTurnOverRank": 10,
      "createdAt": "2020-01-01T00:00:00+00:00",
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      },
      "businessCustomer": true,
      "defaultAddress": {
        "id": "<string>",
        "vatId": "DE123456789",
        "type": "TYPE_DEFAULT",
        "default": "true",
        "status": "active",
        "city": "Berlin",
        "zip": "12345",
        "street": "Musterstraße",
        "houseNumber": "1a",
        "countryCode": "DE",
        "companyName": "ACME Inc.",
        "salutation": "Herr",
        "addition": "c/o John Doe",
        "costCentre": "123456789",
        "firstName": "John",
        "lastName": "Doe"
      },
      "defaultInvoiceAddress": {
        "id": "<string>",
        "vatId": "DE123456789",
        "type": "TYPE_DEFAULT",
        "default": "true",
        "status": "active",
        "city": "Berlin",
        "zip": "12345",
        "street": "Musterstraße",
        "houseNumber": "1a",
        "countryCode": "DE",
        "companyName": "ACME Inc.",
        "salutation": "Herr",
        "addition": "c/o John Doe",
        "costCentre": "123456789",
        "firstName": "John",
        "lastName": "Doe"
      },
      "defaultEmailAddress": {
        "id": "00000000-0000-0000-0000-000000000000",
        "email": "john.doe@example.com",
        "receiverName": "John Doe",
        "type": "TYPE_COMPANY",
        "default": "true"
      },
      "defaultInvoiceEmailAddress": {
        "id": "00000000-0000-0000-0000-000000000000",
        "email": "john.doe@example.com",
        "receiverName": "John Doe",
        "type": "TYPE_COMPANY",
        "default": "true"
      },
      "defaultPaymentMethod": {},
      "isPartner": true
    }
  ],
  "meta": {
    "pagination": {
      "totalItems": 123,
      "itemsPerPage": 123,
      "currentPage": 123,
      "lastPage": 123,
      "pageTotalItems": 123
    }
  }
}

API documentation

User

Tenant

Feature

Entitlement

User & permissions

Settings

Payment

Analytics

Customer

Billing

Dunning

Subscription

Offers

Catalogue

Checkout

Accounting

Taxes

Authorizations

Query Parameters

Response