GET
/
customers
/
{id}
curl -X GET \
 /customers/{id} \
 --header "Authorization: Bearer <token>"
{
  "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,
  "taxExempt": "auto",
  "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",
  "emailAddresses": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "john.doe@example.com",
      "receiverName": "John Doe",
      "type": "TYPE_COMPANY",
      "default": "true"
    }
  ],
  "addresses": [
    {
      "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"
    }
  ],
  "customerGroup": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>"
  },
  "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": {
    "id": "<string>",
    "gatewayName": "wallet",
    "type": "sepa_debit",
    "default": true,
    "status": "active",
    "enabled": true,
    "name": "<string>",
    "creationDate": "2023-11-07T05:31:56Z",
    "expirationDate": "2023-11-07T05:31:56Z",
    "card": {
      "brand": "Visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2022,
      "cardHolder": "Max Mustermann"
    },
    "sepaDebit": {
      "iban": "DE8937*********3232",
      "bic": "COBADEFFXXX",
      "mandateReference": "MNDT-2021-123456",
      "signingDate": "2021-01-01T00:00:00+00:00"
    },
    "paypal": {
      "email": "max@mustermann.de",
      "billingAgreementId": "I-1J5gqz2eZvKYlo2C2X2X2X2X"
    }
  },
  "contactPerson": {
    "id": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "avatar": "<string>"
  },
  "isPartner": true,
  "partner": {
    "id": "ad8f7e7d-3b3b-4b3b-8b3b-3b3b3b3b3b3b",
    "name": "John Doe",
    "number": "123456",
    "email": "partner@example.com"
  }
}

Authorizations

​
Authorization
string
header
required

Value for the Authorization header parameter.

Path Parameters

​
id
string
required

Customer identifier

Response

200
application/json
Customer resource
​
countryCode
string
required
Example:

"DE"

​
id
string
Example:

"00000000-0000-0000-0000-000000000000"

​
customerNumber
string
Required string length: 2 - 255
Example:

"CUSTOMER-000"

​
timeZone
string
default:Europe/Berlin
Example:

"Europe/Berlin"

​
firstName
string | null

Can be empty if the customer is a company.

Required string length: 2 - 255
Example:

"John"

​
lastName
string | null

Can be empty if the customer is a company.

Required string length: 2 - 255
Example:

"Doe"

​
currencyCode
string

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

Example:

"EUR"

​
companyName
string | null
Required string length: 2 - 255
Example:

"Acme Inc."

​
vatId
string | null
Required string length: 2 - 255
Example:

"DE123456789"

​
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

​
taxExempt
enum<string>
Available options:
auto,
exempt
​
datevId
string | null

The ID of the customer in DATEV

Required string length: 2 - 255
Example:

"123456789"

​
commercialRegisterName
string | null

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

Example:

"Amtsgericht Berlin (Charlottenburg)"

​
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"

​
status
enum<string>
default:STATUS_ACTIVE
Available options:
STATUS_ACTIVE,
STATUS_ARCHIVED,
STATUS_SUSPENDED
Example:

"STATUS_ACTIVE"

​
gender
enum<string>

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

Available options:
male,
female,
diverse
Example:

"male"

​
phone
string | null
Required string length: 2 - 255
Example:

"+49 123 456789"

​
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"

​
totalTurnOverRank
integer | null

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

Example:

10

​
createdAt
string
Example:

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

​
emailAddresses
object[]
​
addresses
object[]
​
customerGroup
object | null

The customer group of the customer.

​
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" }
​
businessCustomer
boolean
​
defaultAddress
object | null

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

​
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.

​
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.

​
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.

​
defaultPaymentMethod
object | null

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

​
contactPerson
object | null

The contact person of the customer.

​
isPartner
boolean

Indicates if the customer is a partner.

​
partner
object | null

The partner of the customer. If a partner is assigned, all existing and future subscriptions of the customer will be billed to the default payment method and invoice address of the partner.