Get customers

cURL

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

{
  "data": [
    {
      "countryCode": "DE",
      "id": "00000000-0000-0000-0000-000000000000",
      "customerNumber": "CUSTOMER-000",
      "timeZone": "Europe/Berlin",
      "firstName": "John",
      "lastName": "Doe",
      "currencyCode": "EUR",
      "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": {
        "email": "[email protected]",
        "receiverName": "John Doe",
        "type": "TYPE_COMPANY",
        "id": "00000000-0000-0000-0000-000000000000",
        "default": "true"
      },
      "defaultInvoiceEmailAddress": {
        "email": "[email protected]",
        "receiverName": "John Doe",
        "type": "TYPE_COMPANY",
        "id": "00000000-0000-0000-0000-000000000000",
        "default": "true"
      },
      "defaultPaymentMethod": {},
      "isPartner": true
    }
  ],
  "meta": {
    "pagination": {
      "totalItems": 123,
      "itemsPerPage": 123,
      "currentPage": 123,
      "lastPage": 123,
      "pageTotalItems": 123
    }
  }
}

GET

customers

cURL

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

{
  "data": [
    {
      "countryCode": "DE",
      "id": "00000000-0000-0000-0000-000000000000",
      "customerNumber": "CUSTOMER-000",
      "timeZone": "Europe/Berlin",
      "firstName": "John",
      "lastName": "Doe",
      "currencyCode": "EUR",
      "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": {
        "email": "[email protected]",
        "receiverName": "John Doe",
        "type": "TYPE_COMPANY",
        "id": "00000000-0000-0000-0000-000000000000",
        "default": "true"
      },
      "defaultInvoiceEmailAddress": {
        "email": "[email protected]",
        "receiverName": "John Doe",
        "type": "TYPE_COMPANY",
        "id": "00000000-0000-0000-0000-000000000000",
        "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

Customer collection

data

object[]

Show child attributes

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<date-time>

Example:

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

data.customFields

object

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

Show child attributes

data.customFields.{key}

string

Example:

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

data.businessCustomer

boolean

data.defaultAddress

object

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

Show child attributes

data.defaultAddress.id

string

data.defaultAddress.vatId

string | null

VAT ID, which will be used to bill to. If not provided, we will use the customer vat id.

Example:

"DE123456789"

data.defaultAddress.type

enum<string>

Available options:

TYPE_DEFAULT,

TYPE_INVOICE

Example:

"TYPE_DEFAULT"

data.defaultAddress.default

boolean

Example:

"true"

data.defaultAddress.status

enum<string>

Available options:

active,

archived

Example:

"active"

data.defaultAddress.city

string

Example:

"Berlin"

data.defaultAddress.zip

string

Example:

"12345"

data.defaultAddress.street

string

Example:

"Musterstraße"

data.defaultAddress.houseNumber

string

Example:

"1a"

data.defaultAddress.countryCode

string

Example:

"DE"

data.defaultAddress.companyName

string | null

Company name, which will be used to bill to.

Example:

"ACME Inc."

data.defaultAddress.salutation

enum<string>

Available options:

Firma,

Herr,

Frau

Example:

"Herr"

data.defaultAddress.addition

string | null

Additional address information, which will be shown on generated documents like invoices, reminders, etc.

Example:

"c/o John Doe"

data.defaultAddress.costCentre

string | null

Cost centre, which will be shown on generated documents like invoices, reminders, etc.

Example:

"123456789"

data.defaultAddress.firstName

string | null

First name, which will be shown on generated documents like invoices, reminders, etc.

Example:

"John"

data.defaultAddress.lastName

string | null

Last name, which will be shown on generated documents like invoices, reminders, etc.

Example:

"Doe"

data.defaultInvoiceAddress

object

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.

Show child attributes

data.defaultInvoiceAddress.id

string

data.defaultInvoiceAddress.vatId

string | null

VAT ID, which will be used to bill to. If not provided, we will use the customer vat id.

Example:

"DE123456789"

data.defaultInvoiceAddress.type

enum<string>

Available options:

TYPE_DEFAULT,

TYPE_INVOICE

Example:

"TYPE_DEFAULT"

data.defaultInvoiceAddress.default

boolean

Example:

"true"

data.defaultInvoiceAddress.status

enum<string>

Available options:

active,

archived

Example:

"active"

data.defaultInvoiceAddress.city

string

Example:

"Berlin"

data.defaultInvoiceAddress.zip

string

Example:

"12345"

data.defaultInvoiceAddress.street

string

Example:

"Musterstraße"

data.defaultInvoiceAddress.houseNumber

string

Example:

"1a"

data.defaultInvoiceAddress.countryCode

string

Example:

"DE"

data.defaultInvoiceAddress.companyName

string | null

Company name, which will be used to bill to.

Example:

"ACME Inc."

data.defaultInvoiceAddress.salutation

enum<string>

Available options:

Firma,

Herr,

Frau

Example:

"Herr"

data.defaultInvoiceAddress.addition

string | null

Additional address information, which will be shown on generated documents like invoices, reminders, etc.

Example:

"c/o John Doe"

data.defaultInvoiceAddress.costCentre

string | null

Cost centre, which will be shown on generated documents like invoices, reminders, etc.

Example:

"123456789"

data.defaultInvoiceAddress.firstName

string | null

First name, which will be shown on generated documents like invoices, reminders, etc.

Example:

"John"

data.defaultInvoiceAddress.lastName

string | null

Last name, which will be shown on generated documents like invoices, reminders, etc.

Example:

"Doe"

data.defaultEmailAddress

object

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

Show child attributes

data.defaultEmailAddress.email

string<email>

required

Maximum string length: 255

Example:

"[email protected]"

data.defaultEmailAddress.receiverName

string

required

Maximum string length: 255

Example:

"John Doe"

data.defaultEmailAddress.type

enum<string>

required

Available options:

TYPE_COMPANY,

TYPE_INVOICE

Example:

"TYPE_COMPANY"

data.defaultEmailAddress.id

string

Example:

"00000000-0000-0000-0000-000000000000"

data.defaultEmailAddress.default

boolean

Example:

"true"

data.defaultInvoiceEmailAddress

object

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.

Show child attributes

data.defaultInvoiceEmailAddress.email

string<email>

required

Maximum string length: 255

Example:

"[email protected]"

data.defaultInvoiceEmailAddress.receiverName

string

required

Maximum string length: 255

Example:

"John Doe"

data.defaultInvoiceEmailAddress.type

enum<string>

required

Available options:

TYPE_COMPANY,

TYPE_INVOICE

Example:

"TYPE_COMPANY"

data.defaultInvoiceEmailAddress.id

string

Example:

"00000000-0000-0000-0000-000000000000"

data.defaultInvoiceEmailAddress.default

boolean

Example:

"true"

data.defaultPaymentMethod

object

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.

API documentation

User

Tenant

Feature

Entitlement

User & permissions

Settings

Payment

Analytics

Customer

Billing

Dunning

Subscription

Offers

Catalogue

Checkout

Accounting

Taxes

Authorizations

Query Parameters

Response