Create customer

post

https://api.instellix.io/v2/customers

A new customer can be created together with their addresses (at least one) and properties (optional). The ident is required and must be unique.

Query Params

slimResponse

boolean

Defaults to false

If set to true, the response objects will be smaller and not contain nested collection fields, i.e. Addresses.

Body Params

The representation of a customer. Customers are assigned addresses and properties. Other objects are linked to the customer via the unique ident, which can be an external reference such as a customer number.

addresses

array of objects

required

length ≥ 1

The addresses of the customer. Must not be empty.

addresses*

An address create request that is assigned to a specific debtorId. Can be of addressType INVOICE or SHIPPING.

academicTitle

string

length ≤ 255

Size must be between 0 and 255.

addressAddition

string

length ≤ 255

Optional additional address information. Size must be between 0 and 255.

addressIdent

string

length between 1 and 100

Unique external reference. If not provided NBX will auto generate a UUID. Must have size between 1 and 100 and match with the regular expression '[a-zA-Z0-9_.~-]{1,100}'.

addressType

string

required

Cannot be amended after the initial POST. Must not be null. Must be one of:


INVOICE
SHIPPING

agencyProfessionTitle

string

length ≤ 255

Agency Profession Title. Size must be between 0 and 255.

city

string

length ≤ 255

City. Size must be between 0 and 255.

company

string

length ≤ 255

Company name. Size must be between 0 and 255.

country

string

required

Country code for country of address. Uses Alpha-2 or Alpha3 code (ISO 3166): https://www.iban.com/country-codes. Must not be null.

department

string

length ≤ 255

Department within a company. Size must be between 0 and 255.

eInvoicingParameters

object

Provides information needed to handle e-invoicing.

string

length ≤ 255

Recipient's email. It becomes mandatory for addresses of addressType INVOICE and preferredDocumentDelivery EMAIL. Size must be between 0 and 255.

firstname

string

length ≤ 255

First name of recipient. Size must be between 0 and 255.

gender

string

Recipient's gender. Must be one of:


MALE
FEMALE
OTHER
NOTSET

lastname

string

length ≤ 255

Last name of recipient. Size must be between 0 and 255.

postOfficeBox

string

length ≤ 255

Number of post office box. Size must be between 0 and 255.

preferredDocumentDelivery

string

Defaults to NONE

Defines the preferred way of delivering documents to this customer. Only used for Addresses of Type INVOICE. When set to EMAIL and addressType is INVOICE, the field email must be filled. Must be one of:


EMAIL
LETTER
NONE

properties

array of objects

Array of properties assigned to the specific address.

properties

state

string

length ≤ 255

State. Size must be between 0 and 255.

stateCode

string

length ≤ 255

State code. ISO 3166-2 subdivision code. Size must be between 0 and 255.

street

string

length ≤ 255

Name of street. Size must be between 0 and 255.

streetNo

string

length ≤ 255

Street Number. Size must be between 0 and 255.

taxNumber

string

length ≤ 32

The taxNumber is the local country tax number given to a legal entity by their tax authority such as the German Steuernummer or Italian Codice Fiscale. Size must be between 0 and 32.

validationStatus

string

Status of address validation if required by configured tax provider. Must be one of:


TAXABLE
NON_TAXABLE
VALIDATION_PENDING
VALIDATION_NOT_REQUIRED
NOT_VALIDATED
VALIDATION_FAILED

vatId

string

length ≤ 20

Also known as VAT identification number (VATIN). An identifier used by countries for Value Added Tax purposes to identify legal entities, especially in the EU. Size must be between 0 and 20.

zip

string

length ≤ 10

Postcode. Size must be between 0 and 10.

contractorReferenceIdent

string

length ≤ 255

Contractor (reference) id which can be used for example as customer support ident by third parties' system. Size must be between 0 and 255.

contractorReferenceType

string

length ≤ 255

Additional type that can be used to distinguish contractor reference ident, e.g. DEALER_ID or CUSTOMER_ID. Size must be between 0 and 255.

customerType

string

Type of the customer. Must be one of:


B2B
B2C
AFFILIATED

debtorAccountNumber

int64

Can be either set at customer creation, in which case the associated debtor booking account will receive the provided number, or set by the nitrobox system automatically.

dunning

object | null

The customer dunning configuration.

ident

string

required

length between 1 and 100

Unique external reference. Must have size between 1 and 100 and match with the regular expression '[a-zA-Z0-9_.~-]{1,100}'.

language

string

The language of the customer. Should be in ISO 639-1 ('de') format and if given must match to the used Business Segment.

properties

array of objects

Set of properties assigned to the specific customer.

properties

taxClassifications

array of objects | null

Updates a tax classification of a customer with a validity period.

taxClassifications

tenantId

int64

Is set by the Nitrobox system. Any values entered for GET, POST and PUT requests will be overwritten.

201The request has been fulfilled, resulting in the creation of a new resource.

4XXerror response for all http error codes in range 4XX

5XXerror response for all http error codes in range 5XX