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.

Was this page helpful?

Suggest editsRaise issue