POST
/
customers
curl -X POST \
 /customers \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <token>" \
 --data '{
    "currencyCode": "EUR",
    "timeZone": "Europe\/Berlin",
    "invoiceEmail": "john.doe@example.com",
    "datevId": "123456789",
    "vatId": "DE123456789",
    "companyName": "Acme Inc.",
    "commercialRegisterName": "Amtsgericht Berlin (Charlottenburg)",
    "commercialRegisterNumber": "HRB 123456",
    "phone": "+49 123 456789",
    "street": "Musterstra\u00dfe 1",
    "houseNumber": "1a",
    "zip": "12345",
    "city": "Berlin",
    "addition": "c\/o John Doe",
    "customFields": {
        "field1": "value1",
        "field2": "value2"
    }
}'
{
  "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.

Body

The new Customer resource
​
countryCode
any | null
required
​
email
string
required

The email address used for e-mail communication. This is also the username for the customer login. This needs to be unique.

Required string length: 2 - 255
Example:

"john.doe@example.com"

​
currencyCode
string | null

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

Example:

"EUR"

​
customerGroup
any | null

The customer group of the customer.

​
contactPerson
any | null

The contact person of the customer.

​
timeZone
string | null
default:Europe/Berlin

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

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"

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

​
invoiceEmail
string | null

This email will be used for sending invoices to the customer. If not provided, we use the default e-mail address.

Required string length: 2 - 255
Example:

"john.doe@example.com"

​
datevId
string | null

The ID of the customer in DATEV. If not provided, we will generate a datev id, when the "accounting.useDebitorAccounts" setting is set to true.

Required string length: 2 - 255
Example:

"123456789"

​
gender
enum<string>

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

Available options:
male,
female,
diverse
Example:

"male"

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

"DE123456789"

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

"Acme Inc."

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

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

"+49 123 456789"

​
customerNumber
string | null

Can be empty. In this case the customer number is generated automatically.

Required string length: 2 - 255
Example:

"CUSTOMER-000"

​
street
string | null

The street of the customer. If not provided, we will use empty string.

Required string length: 2 - 255
Example:

"Musterstraße 1"

​
houseNumber
string | null

The house number of the customer. If not provided, we will use empty string.

Maximum length: 255
Example:

"1a"

​
zip
string | null

The zip code of the customer. If not provided, we will use empty string.

Required string length: 2 - 255
Example:

"12345"

​
city
string | null

The city of the customer. If not provided, we will use empty string.

Required string length: 2 - 255
Example:

"Berlin"

​
addition
string | null

Additional address line of the customer. If not provided, we will use empty string.

Required string length: 2 - 255
Example:

"c/o John Doe"

​
invoiceAddress
any | null

An invoice address for the customer. If not provided, we will use the default address.

​
taxExempt
enum<string>
default:auto

The tax exemption status of the customer.

Possible values:

  • exempt: The customer will never be charged with taxes.
  • auto: The customer will be charged with taxes based on their country and vat id status. If the customer is eligble for reverse-charge the customer will not be charged with taxes.
Available options:
auto,
exempt
Example:

"auto"

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

Response

201
application/json
Customer resource created
​
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