Core Concept

The customer API setup is build around a top-level customer resource and independent sub-resources for addresses and contact person. The core resource has a one-to-many relationship with its sub-resources. Thus, a customer can have many addresses (e.g. billing, shipping) and many contact person (e.g. sales rep, support agent).

Definition Customer: An address with role customer.

Resources

The customer API consists of three resources: Customer, Address, Contact Person. In the following each resource will be introduced and the associated API calls are listed.

Customer

The customer object contains the following information:

• meta data: e.g. id, number (customer number), createdAt, updatedAt, groups
  • customerType: can be person or company
    • company: name field is required
    • person: firstname and lastname are required. Note: Regardless of the customerType we display currently only name value in the xentral UI. Thus, firstname and lastname values are merged into name field. Via View Customer API you have always access to firstname and lastname values of a customer of customerType person.
• contact data: e.g. phone, email, website
• bank account data: e.g. IBAN, BIC, SEPA details
• financial data: e.g. tax data, payment terms data, paymentMethod, creditLimit
• shipping data: e.g. freeShippingFrom, shippingMethod, deliveryBan
• document delivery data: e.g. email recipients for business documents like offers and invoice
• links: references to associated sub-resources addresses and contact person

The customer object offers the following API calls:

Address

A customer can have many addresses. An address object contains the following information:

• type (required), must be one of the following values:
  • masterdata: The primary customer address, which is used by the List Customer API if you want to query for address variables like street and city.
    billingaddress: An alternative billing address for a given customer
  • deliveryaddress: A customer can have multiple delivery addresses.
• primary address data (required): name, street, zip, city, country
• secondary address data: e.g. addressSupplement, department
• additional delivery information: contact details ( email, phone, gln) and delivery details taxType, defaultDeliveryAddress, vatID)
• links: reference to associated Customer core-resource

Contact Person

A customer can have many contact persons. A contact person object contains the following information:

• primary contact person data (required): name
• secondary contact person data: e.g. birthday, department, position
• address: name, street, zip, city, country
• contact data: e.g. phone, email, salutation
• groups: id of the groups the contact person belongs to
• links: reference to associated Customer core-resource

Reference Handling

In the responses of View and List operations of all resources (customer, address, contact person) you’ll find something like:

"links": {
    "links": {
      "self": "http://localhost/api/v2/customers/2",
      "contactPersons": "http://localhost/api/customers/2/contactPerson",
      "address": "http://localhost/api/customers/2/addresses" 
    }

These links let clients fetch or manipulate a specific resource without having to guess the URL structure.