--- updatedAt: 2026-07-03T13:05:45.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # 🔒 Create customer V3 This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues. This endpoint requires the following scopes: `customer:create`. Create a new customer. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Xentral Business Documents API v3", "description": "The Xentral Business Documents API v3 for working with sales orders, offers, invoices, credit notes, delivery notes, return orders, purchase orders, proforma invoices and productions.\n\nIndividual endpoints marked as *Beta* may still change without prior notice — see the respective endpoint descriptions.\n\nRequest payloads may contain properties that an endpoint does not define; these are ignored rather than rejected. Nothing is stored for them and no error is returned, so check the response body to confirm which values were actually applied.", "contact": { "name": "API Support", "url": "https://xentral.com", "email": "api@xentral.com" }, "version": "0.2.0" }, "servers": [ { "url": "https://{xentralId}.xentral.biz", "description": "Your xentral instance", "variables": { "xentralId": { "default": "my-company", "description": "Your Xentral instance ID" } } }, { "url": "https://{domain}", "description": "Xentral with a custom domain", "variables": { "domain": { "default": "demo.xentral.com", "description": "Your Xentral custom domain" } } } ], "components": { "schemas": { "AdditionalContactInformationData": { "required": [ "key", "value" ], "properties": { "key": { "description": "Contact information type/key", "type": "string", "example": "linkedin" }, "value": { "description": "Contact information value. Set to null to delete the entry.", "type": [ "string", "null" ], "example": "linkedin.com/in/lschneider" } }, "type": "object" }, "AddressReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the address", "type": "string", "example": "13" } }, "type": "object" }, "CommunicationData": { "properties": { "language": { "description": "Language preference. The two-letter code of a language that exists in the system settings.", "type": "string", "maxLength": 2, "minLength": 2, "example": "DE" }, "website": { "description": "Website URL", "type": "string", "example": "https://xentral.com" }, "allowTrackingEmails": { "description": "Allow tracking emails", "type": "boolean", "default": true, "example": true }, "allowFollowUpConfirmations": { "description": "Allow follow-up confirmations", "type": "boolean", "default": true, "example": true }, "allowMarketingEmails": { "description": "Allow marketing emails", "type": "boolean", "default": true, "example": false }, "additionalContactInformation": { "description": "Additional contact information entries", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalContactInformationData" } } }, "type": "object" }, "ContactPerson": { "description": "Contact Person object", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimestampsResource" }, { "properties": { "id": { "description": "ID of contact person", "type": "string", "example": "17" }, "type": { "description": "Type of contact person", "type": [ "string", "null" ], "enum": [ "mrs", "mr", "company", "other" ], "example": "mr" }, "name": { "description": "Name of contact person", "type": "string", "example": "Alice Smith" }, "title": { "description": "Title of contact person", "type": [ "string", "null" ], "example": "Ms." }, "salutation": { "description": "Salutation of contact person", "type": [ "string", "null" ], "example": "Dear Alice," }, "department": { "description": "Department of contact person", "type": [ "string", "null" ], "example": "Sales" }, "subDepartment": { "description": "Sub-Department of contact person", "type": [ "string", "null" ], "example": "Customer Service" }, "street": { "description": "Street of contact person address", "type": [ "string", "null" ], "example": "123 Main St" }, "addressSupplement": { "description": "Address supplement of contact person address", "type": [ "string", "null" ], "example": "Suite 100" }, "zipCode": { "description": "Zip code of contact person address", "type": [ "string", "null" ], "example": "12345" }, "city": { "description": "City of contact person address", "type": [ "string", "null" ], "example": "Springfield" }, "country": { "description": "Country of contact person address", "type": [ "string", "null" ], "example": "US" }, "state": { "description": "State of contact person address", "type": [ "string", "null" ], "example": "CA" }, "phone": { "description": "Phone number of contact person", "type": [ "string", "null" ], "example": "+1-234-567-8900" }, "mobile": { "description": "Mobile number of contact person", "type": [ "string", "null" ], "example": "+1-800-567-8900" }, "fax": { "description": "Fax number of contact person", "type": [ "string", "null" ], "example": "+1-234-567-8901" }, "email": { "description": "Email address of contact person", "type": [ "string", "null" ], "example": "alice@example.com" }, "contactPersonDetails": { "description": "Contact person details", "properties": { "position": { "type": [ "string", "null" ], "example": "Head of Controlling" }, "birthday": { "type": [ "string", "null" ], "format": "date", "example": "1980-05-21" }, "language": { "type": [ "string", "null" ], "example": "DE" }, "allowMarketingEmails": { "type": "boolean", "example": false }, "internalNote": { "type": [ "string", "null" ], "example": "Head of Controlling" }, "remarks": { "type": [ "string", "null" ], "example": "Head of Controlling" } }, "type": "object", "example": { "position": "Head of Controlling", "birthday": "1978-04-12", "language": "DE", "allowMarketingEmails": false, "internalNote": "Key decision‑maker for raw‑material contracts; prefers email after 17:00 CET.", "remarks": "Speaks fluent English, French and Mandarin. Holds a PhD in Economics." } }, "groups": { "description": "Group information", "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "example": [ { "id": "1" } ] } }, "type": "object" } ] }, "CreateCustomerData": { "required": [ "primaryAddress" ], "properties": { "number": { "description": "Customer number", "type": "string", "example": "700042" }, "deviatingDebtorAccountNumber": { "description": "Deviating debtor account number for accounting", "type": "string", "example": "711999" }, "routingId": { "description": "Routing ID (German: Leitweg-ID) used as the buyer reference on e-invoices. Takes precedence over the legacy free field 20.", "type": "string", "example": "04011000-1234512345-06" }, "mainProject": { "$ref": "#/components/schemas/ProjectReferenceData", "description": "Main project the customer belongs to" }, "primaryAddress": { "$ref": "#/components/schemas/CustomerAddressData", "description": "Primary address information for the customer" }, "deviatingBillingAddress": { "$ref": "#/components/schemas/CustomerAddressData", "description": "Deviating billing address information" }, "communication": { "$ref": "#/components/schemas/CommunicationData", "description": "Communication preferences and settings" }, "financials": { "$ref": "#/components/schemas/FinancialsData", "description": "Financial information and settings" }, "fulfillment": { "$ref": "#/components/schemas/FulfillmentData", "description": "Fulfillment and delivery settings" }, "documentDelivery": { "$ref": "#/components/schemas/DocumentDeliveryData", "description": "Document delivery preferences" }, "accountManager": { "$ref": "#/components/schemas/AddressReferenceData", "description": "Account manager reference" }, "salesManager": { "$ref": "#/components/schemas/SalesManagerData", "description": "Sales manager with commission" }, "originSalesChannel": { "$ref": "#/components/schemas/SalesChannelReferenceData", "description": "Origin sales channel reference" }, "groups": { "description": "Groups the customer belongs to", "type": "array", "items": { "$ref": "#/components/schemas/GroupReferenceData" } }, "customerRoles": { "description": "Customer roles associated with projects. Only roles that are currently active (based on validFrom and expiresAt dates) will be inserted.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerRoleData" } }, "customFields": { "description": "Custom fields for additional custom data", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldsData" } }, "notes": { "description": "Notes for the customer", "type": "string", "example": "Key account – high‑value contracts expected in FY 2026." }, "tags": { "description": "Tags assigned to the customer. The passed list replaces the currently assigned tags; omit the property to leave them unchanged. Each entry references an existing tag by `id` or names a tag by `title`, which is created if it does not exist; exactly one of the two.", "type": "array", "items": { "$ref": "#/components/schemas/TagReferenceData" } } }, "type": "object" }, "CustomFieldsData": { "required": [ "key", "value" ], "properties": { "key": { "description": "Custom field key: either a `customField` key or the key of a custom field configured in your Xentral instance. Which keys are accepted is documented on the `customFields` property of each resource.", "type": "string", "example": "customField1" }, "label": { "description": "Custom field label. Accepted for symmetry with the read payload, but ignored on write.", "type": "string", "example": "lifecycle" }, "value": { "description": "Custom field value. Pass `null` to clear the field.", "type": [ "string", "null" ], "example": "prospect" } }, "type": "object" }, "Customer": { "description": "Customer entity", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimestampsResource" }, { "properties": { "id": { "description": "ID of the customer", "type": "string", "example": "1" }, "number": { "description": "Customer number", "type": "string", "example": "700042" }, "deviatingDebtorAccountNumber": { "description": "Deviating customer number for accounting", "type": [ "string", "null" ], "example": "711999" }, "routingId": { "description": "Routing ID (German: Leitweg-ID) used as the buyer reference on e-invoices. Takes precedence over the legacy free field 20.", "type": [ "string", "null" ], "example": "04011000-1234512345-06" }, "mainProject": { "description": "Main project the customer belongs to", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ], "example": { "id": "1" } }, "primaryAddress": { "oneOf": [ { "$ref": "#/components/schemas/PostalAddress", "description": "Primary address information for the customer" }, { "type": "null" } ], "description": "Primary address information for the customer" }, "deviatingBillingAddress": { "oneOf": [ { "$ref": "#/components/schemas/PostalAddress", "description": "Deviating billing address information for the customer" }, { "type": "null" } ], "description": "Deviating billing address information for the customer" }, "communication": { "description": "Communication preferences and settings for the customer", "properties": { "language": { "type": [ "string", "null" ], "example": "DE" }, "website": { "type": [ "string", "null" ], "example": "https://www.xentral.com" }, "allowTrackingEmails": { "type": "boolean", "example": true }, "allowFollowUpConfirmations": { "type": "boolean", "example": true }, "allowMarketingEmails": { "type": "boolean", "example": false }, "additionalContactInformation": { "description": "Additional contact information entries", "type": "array", "items": { "properties": { "key": { "type": "string", "example": "Skype" }, "value": { "type": "string", "example": "xentral.support" } }, "type": "object" }, "example": [ { "key": "Skype", "value": "xentral.support" }, { "key": "LinkedIn", "value": "https://www.linkedin.com/company/xentralsoftware" } ] } }, "type": "object", "example": { "language": "DE", "website": "https://www.xentral.com", "allowTrackingEmails": true, "allowFollowUpConfirmations": true, "allowMarketingEmails": false, "additionalContactInformation": [ { "key": "Skype", "value": "xentral.support" }, { "key": "LinkedIn", "value": "https://www.linkedin.com/company/xentralsoftware" } ] } }, "financials": { "description": "Financial information and settings for the customer", "properties": { "primaryBankAccount": { "properties": { "bankName": { "description": "Masked by default. Requires customer:readBanking scope for unmasked value.", "type": [ "string", "null" ], "example": "XYZ***" }, "accountHolder": { "description": "Masked by default. Requires customer:readBanking scope for unmasked value.", "type": [ "string", "null" ], "example": "Xen**************************" }, "iban": { "description": "Masked by default (e.g. DE89**************3000). Requires customer:readBanking scope for unmasked value.", "type": [ "string", "null" ], "example": "DE89**************3000" }, "bic": { "description": "Masked by default. Requires customer:readBanking scope for unmasked value.", "type": [ "string", "null" ], "example": "*******FXXX" }, "sepa": { "properties": { "isCompanySepa": { "type": "boolean", "example": true }, "mandateReference": { "description": "Masked by default. Requires customer:readBanking scope for unmasked value.", "type": [ "string", "null" ], "example": "TN2*********************" }, "mandateReferenceChange": { "type": "boolean", "example": false }, "mandateReferenceDate": { "type": [ "string", "null" ], "example": "2025-03-01" }, "usage": { "type": [ "string", "null" ], "enum": [ "single", "recurring" ], "example": "recurring" }, "isInitialMandate": { "type": "boolean", "example": true }, "remark": { "type": [ "string", "null" ], "example": "Standard SEPA mandate for monthly invoice settlement" } }, "type": "object" } }, "type": "object" }, "tax": { "properties": { "vatId": { "type": [ "string", "null" ], "example": "DE112233445" }, "taxNumber": { "type": [ "string", "null" ], "example": "l2/345/67890" }, "taxation": { "type": [ "string", "null" ], "enum": [ "domestic", "eu", "export", "exempt" ], "example": "eu" }, "taxDisplay": { "type": [ "string", "null" ], "enum": [ "automatic", "net", "gross" ], "example": "gross" }, "useDeliveryThreshold": { "type": "boolean", "example": true }, "customsInformation": { "type": [ "string", "null" ], "example": "l2/345/67890 – Integrated circuits, origin DE, duty‑free under EU‑US agreement" } }, "type": "object" }, "paymentTerms": { "properties": { "fixedPaymentTerms": { "type": "boolean", "example": true }, "paymentTargetDays": { "type": "integer", "example": 30 }, "paymentTargetDiscount": { "type": "number", "format": "float", "example": 2 }, "paymentTargetDiscountDays": { "type": "integer", "example": 10 } }, "type": "object" }, "paymentMethod": { "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ] }, "supplierNumberForCustomer": { "type": [ "string", "null" ], "example": "TN‑EX‑70042" }, "subscriptionPaymentMethod": { "type": [ "string", "null" ], "enum": [ "directDebit", "invoice" ], "example": "invoice" }, "defaultCurrency": { "type": [ "string", "null" ], "example": "EUR" }, "creditLimit": { "type": "number", "format": "float", "example": 25000 } }, "type": "object", "example": { "primaryBankAccount": { "bankName": "XYZ***", "accountHolder": "Xen**************************", "iban": "DE89**************3000", "bic": "*******FXXX", "sepa": { "isCompanySepa": true, "mandateReference": "TN2*********************", "mandateReferenceChange": false, "mandateReferenceDate": "2025-03-01", "usage": "recurring", "isInitialMandate": true, "remark": "Standard SEPA mandate for monthly invoice settlement" } }, "tax": { "vatId": "DE112233445", "taxNumber": "l2/345/67890", "taxation": "eu", "taxDisplay": "gross", "useDeliveryThreshold": true, "customsInformation": "l2/345/67890 – Integrated circuits, origin DE, duty‑free under EU‑US agreement" }, "paymentTerms": { "fixedPaymentTerms": true, "paymentTargetDays": 30, "paymentTargetDiscount": 2, "paymentTargetDiscountDays": 10 }, "paymentMethod": { "id": "1" }, "supplierNumberForCustomer": "TN‑EX‑70042", "subscriptionPaymentMethod": "invoice", "defaultCurrency": "EUR", "creditLimit": 25000 } }, "fulfillment": { "description": "Fulfillment and delivery settings for the customer", "properties": { "shippingMethod": { "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ] }, "freeShippingActive": { "type": "boolean", "example": false }, "freeShippingFrom": { "type": "number", "format": "float", "example": 0 }, "ageCheckRequired": { "type": "boolean", "example": false }, "deliveryTerms": { "type": [ "string", "null" ], "example": "DAP" }, "deliveryBlock": { "type": [ "boolean", "null" ], "example": false }, "deliveryBlockDate": { "type": [ "string", "null" ], "format": "date", "example": "2025-06-10" }, "deliveryBlockReason": { "type": [ "string", "null" ], "example": "" }, "autoCreateDocuments": { "type": [ "string", "null" ], "enum": [ "deliveryNote", "invoice", "deliveryNoteAndInvoice" ], "example": "deliveryNoteAndInvoice" }, "orderQuoteRemarks": { "type": [ "string", "null" ], "example": "Standard delivery schedule – weekdays 08:00‑18:00" }, "commissionConsignmentWarehouse": { "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ] } }, "type": "object", "example": { "shippingMethod": { "id": "1" }, "freeShippingActive": false, "freeShippingFrom": 0, "ageCheckRequired": false, "deliveryTerms": "DAP", "deliveryBlock": false, "deliveryBlockDate": "2025-06-10", "deliveryBlockReason": "", "autoCreateDocuments": "deliveryNoteAndInvoice", "orderQuoteRemarks": "Standard delivery schedule – weekdays 08:00‑18:00", "commissionConsignmentWarehouse": { "id": "1" } } }, "documentDelivery": { "description": "Document delivery preferences for the customer", "properties": { "invoiceAlwaysPaper": { "type": "boolean", "example": false }, "amountInvoicePrints": { "type": [ "integer", "null" ], "example": 1 }, "preferFax": { "type": "boolean", "example": false }, "documentRecipients": { "description": "Document recipients configuration for different document types", "properties": { "offer": { "properties": { "to": { "type": "string", "example": "offer-send@domain.tpl" }, "cc": { "type": "array", "items": { "type": "string" }, "example": [ "offer-send-cc@otherdomain.tpl" ] } }, "type": "object" }, "salesOrder": { "properties": { "to": { "type": "string", "example": "salesOrder-send@domain.tpl" }, "cc": { "type": "array", "items": { "type": "string" }, "example": [ "salesOrder-send-cc@otherdomain.tpl" ] } }, "type": "object" }, "invoice": { "properties": { "to": { "type": "string", "example": "invoice-send@domain.tpl" }, "cc": { "type": "array", "items": { "type": "string" }, "example": [ "invoice-send-cc@otherdomain.tpl" ] } }, "type": "object" }, "creditNote": { "properties": { "to": { "type": "string", "example": "creditNote-send@domain.tpl" }, "cc": { "type": "array", "items": { "type": "string" }, "example": [ "creditNote-send-cc@otherdomain.tpl" ] } }, "type": "object" }, "deliveryNote": { "properties": { "to": { "type": "string", "example": "deliveryNote-send@domain.tpl" }, "cc": { "type": "array", "items": { "type": "string" }, "example": [ "deliveryNote-send-cc@otherdomain.tpl" ] } }, "type": "object" }, "purchaseOrder": { "properties": { "to": { "type": "string", "example": "purchaseOrder-send@domain.tpl" }, "cc": { "type": "array", "items": { "type": "string" }, "example": [ "purchaseOrder-send-cc@otherdomain.tpl" ] } }, "type": "object" }, "dunning": { "properties": { "to": { "type": [ "string", "null" ], "example": "dunning-send@domain.tpl" }, "cc": { "type": "array", "items": { "type": "string" }, "example": [ "dunning-send-cc@otherdomain.tpl" ] } }, "type": "object" } }, "type": "object", "example": { "offer": { "to": "offer-send@domain.tpl", "cc": [ "offer-send-cc@otherdomain.tpl" ] }, "salesOrder": { "to": "salesOrder-send@domain.tpl", "cc": [ "salesOrder-send-cc@otherdomain.tpl" ] }, "invoice": { "to": "invoice-send@domain.tpl", "cc": [ "invoice-send-cc@otherdomain.tpl" ] }, "creditNote": { "to": "creditNote-send@domain.tpl", "cc": [ "creditNote-send-cc@otherdomain.tpl" ] }, "deliveryNote": { "to": "deliveryNote-send@domain.tpl", "cc": [ "deliveryNote-send-cc@otherdomain.tpl" ] }, "purchaseOrder": { "to": "purchaseOrder-send@domain.tpl", "cc": [ "purchaseOrder-send-cc@otherdomain.tpl" ] }, "dunning": { "to": "dunning-send@domain.tpl", "cc": [ "dunning-send-cc@otherdomain.tpl" ] } } } }, "type": "object", "example": { "invoiceAlwaysPaper": false, "amountInvoicePrints": 1, "preferFax": false, "documentRecipients": { "offer": { "to": "offer-send@domain.tpl", "cc": [ "offer-send-cc@otherdomain.tpl" ] }, "salesOrder": { "to": "salesOrder-send@domain.tpl", "cc": [ "salesOrder-send-cc@otherdomain.tpl" ] }, "invoice": { "to": "invoice-send@domain.tpl", "cc": [ "invoice-send-cc@otherdomain.tpl" ] }, "creditNote": { "to": "creditNote-send@domain.tpl", "cc": [ "creditNote-send-cc@otherdomain.tpl" ] }, "deliveryNote": { "to": "deliveryNote-send@domain.tpl", "cc": [ "deliveryNote-send-cc@otherdomain.tpl" ] }, "purchaseOrder": { "to": "purchaseOrder-send@domain.tpl", "cc": [ "purchaseOrder-send-cc@otherdomain.tpl" ] }, "dunning": { "to": "dunning-send@domain.tpl", "cc": [ "dunning-send-cc@otherdomain.tpl" ] } } } }, "customerRoles": { "description": "Projects associated with the customer as a customer role. When id is null, it means all projects in the system.", "type": "array", "items": { "properties": { "project": { "description": "Project associated with the customer", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ], "example": { "id": "1" } }, "validFrom": { "type": [ "string", "null" ], "format": "date", "example": "2024-10-23" }, "expiresAt": { "type": [ "string", "null" ], "format": "date", "example": "2026-10-23" } }, "type": "object" }, "example": [ { "project": { "id": "1" }, "validFrom": "2024-10-23", "expiresAt": "2026-10-23" }, { "project": { "id": "2" }, "validFrom": "2024-11-17", "expiresAt": "2025-11-17" } ] }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "example": [ { "id": "1", "name": "Wholesale" }, { "id": "2", "name": "Retail" } ] }, "accountManager": { "description": "Account manager responsible for the customer", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ], "example": { "id": "1" } }, "salesManager": { "description": "Sales manager responsible for the customer", "properties": { "id": { "type": "string", "example": "1" }, "commission": { "type": [ "number", "null" ], "format": "float", "example": 4.5 } }, "type": [ "object", "null" ], "example": { "id": "1", "commission": 4.5 } }, "originSalesChannel": { "description": "Origin sales channel responsible for the customer", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ], "example": { "id": "1" } }, "customFields": { "description": "Custom fields with their values and metadata", "type": "array", "items": { "properties": { "key": { "type": "string", "example": "customField1" }, "value": { "description": "The custom field value. Its JSON type depends on the sibling `type` field: `string`/`translatable_string` and `date`/`datetime` (as ISO 8601 strings) are strings, `integer`/`float` are numbers, `boolean` is a boolean, and `object` is a JSON object.", "example": "prospect", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "null" } ] }, "label": { "type": "string", "example": "lifecycle" }, "type": { "description": "The data type of the custom field. Legacy custom fields always report `string`.", "type": "string", "enum": [ "string", "integer", "float", "date", "datetime", "boolean", "translatable_string", "object" ], "example": "string" } }, "type": "object" }, "example": [ { "key": "customer_category", "value": "Premium", "label": "Customer Category", "type": "string" }, { "key": "priority_level", "value": "High", "label": "Priority Level", "type": "string" } ] }, "notes": { "description": "Notes added by the Customer", "type": [ "string", "null" ], "example": "Customer prefers morning deliveries" }, "deliveryAddresses": { "description": "Delivery addresses associated with the customer", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryAddress" } }, "contactPersons": { "description": "Contact persons associated with the customer", "type": "array", "items": { "$ref": "#/components/schemas/ContactPerson" } }, "tags": { "description": "Tags assigned to the customer", "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } }, "type": "object" } ], "x-example-ignore": true }, "CustomerAddressData": { "description": "Represents a customer address with contact information for creating customers.", "required": [ "name", "street", "city", "zipCode", "country" ], "properties": { "name": { "type": "string", "example": "Xentral ERP Solutions GmbH" }, "type": { "type": [ "string", "null" ], "enum": [ "mrs", "mr", "company", "other" ], "example": "company" }, "title": { "type": [ "string", "null" ], "example": "Dr." }, "contactPerson": { "type": [ "string", "null" ], "example": "Laura Schneider" }, "salutation": { "type": [ "string", "null" ], "example": "Sehr geehrte Damen und Herren" }, "department": { "type": [ "string", "null" ], "example": "Research & Development" }, "subDepartment": { "type": [ "string", "null" ], "example": "AI Lab" }, "addressSupplement": { "type": [ "string", "null" ], "example": "Gebäude B, 4. Etage" }, "street": { "type": "string", "example": "Innovationsallee 7" }, "zipCode": { "type": "string", "example": "80333" }, "city": { "type": "string", "example": "München" }, "state": { "type": [ "string", "null" ], "example": "BY" }, "country": { "description": "Country (ISO 3166-1 alpha-2).", "type": "string", "maxLength": 2, "pattern": "^[A-Z]{2}$", "example": "DE" }, "gln": { "type": [ "string", "null" ], "example": "4012345000300" }, "email": { "type": [ "string", "null" ], "example": "l.schneider@xentral.com" }, "phone": { "type": [ "string", "null" ], "example": "+4915112345670" }, "mobile": { "type": [ "string", "null" ], "example": "+4917612345671" }, "fax": { "type": [ "string", "null" ], "example": "+4915112345672" } }, "type": "object", "example": { "name": "Xentral ERP Solutions GmbH", "type": "company", "title": "Dr.", "contactPerson": "Laura Schneider", "salutation": "Sehr geehrte Damen und Herren", "department": "Research & Development", "subDepartment": "AI Lab", "addressSupplement": "Gebäude B, 4. Etage", "street": "Innovationsallee 7", "zipCode": "80333", "city": "München", "state": "BY", "country": "DE", "gln": "4012345000300", "email": "l.schneider@xentral.com", "phone": "+4915112345670", "mobile": "+4917612345671", "fax": "+4915112345672" } }, "CustomerPaymentTermsData": { "properties": { "fixedPaymentTerms": { "description": "Fixed payment terms", "type": "boolean", "example": true }, "paymentTargetDays": { "description": "Payment target days", "type": [ "integer", "null" ], "example": 30 }, "paymentTargetDiscount": { "description": "Payment target discount percentage", "type": [ "number", "null" ], "format": "float", "example": 2 }, "paymentTargetDiscountDays": { "description": "Payment target discount days", "type": [ "integer", "null" ], "example": 10 } }, "type": "object" }, "CustomerRoleData": { "properties": { "project": { "$ref": "#/components/schemas/ProjectReferenceData", "description": "Project reference" }, "validFrom": { "description": "Valid from date", "type": "string", "format": "date", "example": "2025-01-01" }, "expiresAt": { "description": "Expires at date", "type": [ "string", "null" ], "format": "date", "example": "2026-12-31" } }, "type": "object" }, "DeliveryAddress": { "description": "Delivery address entity", "required": [ "id", "type", "name", "street", "zipCode", "city", "country", "deliveryDetails" ], "properties": { "id": { "description": "Unique identifier for the delivery address", "type": "string", "example": "1" }, "type": { "description": "Type of the delivery address recipient. Use 'company' for business addresses, 'mrs' for female recipients, 'mr' for male recipients, and 'other' for other types.", "type": [ "string", "null" ], "enum": [ "company", "mrs", "mr", "other" ], "example": "company" }, "name": { "description": "Full name of the delivery address recipient. For companies, this is the company name. For persons, this is the full name.", "type": "string", "example": "Acme Logistics Hub Berlin" }, "title": { "description": "Title of the contact person.", "type": [ "string", "null" ], "example": "Dr." }, "contactPerson": { "description": "Name of the contact person at this delivery address. This is typically used for company addresses to specify who should receive the delivery.", "type": [ "string", "null" ], "example": "Marco Schmidt" }, "salutation": { "description": "Salutation or greeting phrase for the delivery address. Can be used for personalized communication.", "type": [ "string", "null" ], "example": "Hallo Logistics Team" }, "department": { "description": "Department name at the delivery address. Useful for routing deliveries within larger organizations.", "type": [ "string", "null" ], "example": "Logistics" }, "subDepartment": { "description": "Sub department name at the delivery address. Useful for routing deliveries within larger organizations.", "type": [ "string", "null" ], "example": "Distribution Center" }, "addressSupplement": { "description": "Additional address information such as building name, floor, hall, or specific delivery instructions for the location", "type": [ "string", "null" ], "example": "Hall B" }, "street": { "description": "Street name and house number of the delivery address", "type": "string", "example": "Lagerweg 22" }, "zipCode": { "description": "Postal code (ZIP code) of the delivery address", "type": "string", "example": "10437" }, "city": { "description": "City name of the delivery address", "type": "string", "example": "Berlin" }, "state": { "description": "State or region code in ISO 3166-2 format (without country prefix). Required for countries with states/provinces.", "type": [ "string", "null" ], "example": "BE" }, "country": { "description": "Country code in ISO 3166-1 alpha-2 format", "type": "string", "example": "DE" }, "gln": { "description": "Global Location Number (GLN) - a 13-digit number used to uniquely identify physical locations or legal entities globally. Used in supply chain and logistics for automated identification.", "type": [ "string", "null" ], "pattern": "^[0-9]{13}$", "example": "4012345000300" }, "phone": { "description": "Primary phone number for the delivery address. Used for delivery coordination and communication.", "type": [ "string", "null" ], "example": "+491231234567" }, "mobile": { "description": "Mobile phone number for the delivery address contact. Useful for urgent delivery notifications.", "type": [ "string", "null" ], "example": "+49170123456" }, "fax": { "description": "Fax number for the delivery address. Still used by some organizations for official communications.", "type": [ "string", "null" ], "example": "+491231234567-1" }, "email": { "description": "Email address for delivery notifications and communication", "type": [ "string", "null" ], "format": "email", "example": "name@provider.com" }, "deliveryDetails": { "description": "Delivery-specific settings and information for the address", "properties": { "taxType": { "description": "Tax classification for deliveries to this address. 'domestic' for same-country deliveries, 'eu' for EU cross-border, 'export' for non-EU international, 'exempt' for tax-exempt deliveries.", "type": "string", "enum": [ "domestic", "eu", "export", "exempt" ], "example": "domestic" }, "defaultDeliveryAddress": { "description": "Indicates whether this is the default delivery address. Only one delivery address per customer/supplier should be set as default.", "type": "boolean", "example": true }, "termsOfDelivery": { "description": "Incoterms or delivery terms code (e.g., EXW, FOB, CIF, DAP). Defines the responsibilities and costs between buyer and seller during shipping.", "type": [ "string", "null" ], "example": "EXW" }, "vatId": { "description": "VAT identification number for this delivery address. May differ from the main VAT ID for multi-location businesses.", "type": [ "string", "null" ], "example": "DE123456789" }, "remark": { "description": "Internal notes about this delivery address. Not visible externally. Used for operational information like opening hours, special handling instructions, or access codes.", "type": [ "string", "null" ], "example": "Main Berlin hub open 06:00 to 22:00" }, "note": { "description": "Public notes or delivery instructions for this address. May be shared with carriers or printed on delivery documents.", "type": [ "string", "null" ], "example": "Deliveries after 10am only" } }, "type": "object", "example": { "taxType": "domestic", "defaultDeliveryAddress": true, "termsOfDelivery": "EXW", "vatId": "DE123456789", "remark": "Main Berlin hub open 06:00 to 22:00", "note": "Deliveries after 10am only" } } }, "type": "object", "x-example-ignore": true }, "DocumentDeliveryData": { "properties": { "invoiceAlwaysPaper": { "description": "Invoice always paper", "type": "boolean", "example": false }, "amountInvoicePrints": { "description": "Amount of invoice prints", "type": "integer", "example": 1 }, "preferFax": { "description": "Prefer fax delivery", "type": "boolean", "example": false }, "documentRecipients": { "$ref": "#/components/schemas/DocumentRecipientsData", "description": "Document recipients configuration" } }, "type": "object" }, "DocumentRecipientData": { "properties": { "to": { "description": "Primary email recipient", "type": "string", "example": "invoice-send@domain.tpl" }, "cc": { "description": "CC email recipients", "type": "array", "items": { "type": "string" }, "example": [ "invoice-send-cc@otherdomain.tpl" ] } }, "type": "object" }, "DocumentRecipientsData": { "properties": { "offer": { "$ref": "#/components/schemas/DocumentRecipientData", "description": "Offer document recipients" }, "salesOrder": { "$ref": "#/components/schemas/DocumentRecipientData", "description": "Sales order document recipients" }, "invoice": { "$ref": "#/components/schemas/DocumentRecipientData", "description": "Invoice document recipients" }, "creditNote": { "$ref": "#/components/schemas/DocumentRecipientData", "description": "Credit note document recipients" }, "deliveryNote": { "$ref": "#/components/schemas/DocumentRecipientData", "description": "Delivery note document recipients" }, "purchaseOrder": { "$ref": "#/components/schemas/DocumentRecipientData", "description": "Purchase order document recipients" }, "dunning": { "$ref": "#/components/schemas/DocumentRecipientData", "description": "Dunning document recipients" } }, "type": "object" }, "FinancialsData": { "properties": { "primaryBankAccount": { "$ref": "#/components/schemas/PrimaryBankAccountData", "description": "Primary bank account information" }, "tax": { "$ref": "#/components/schemas/TaxData", "description": "Tax information" }, "paymentTerms": { "$ref": "#/components/schemas/CustomerPaymentTermsData", "description": "Payment terms configuration" }, "paymentMethod": { "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodReferenceData", "description": "Payment method reference" }, { "type": "null" } ], "description": "Payment method reference" }, "supplierNumberForCustomer": { "description": "Supplier number for customer", "type": [ "string", "null" ], "example": "TN‑EX‑70042" }, "subscriptionPaymentMethod": { "description": "Subscription payment method", "type": "string", "enum": [ "directDebit", "invoice" ], "example": "invoice" }, "defaultCurrency": { "description": "Default currency", "type": [ "string", "null" ], "maxLength": 3, "minLength": 3, "example": "EUR" }, "creditLimit": { "description": "Credit limit", "type": [ "number", "null" ], "format": "float", "example": 25000 } }, "type": "object" }, "FulfillmentData": { "properties": { "shippingMethod": { "oneOf": [ { "$ref": "#/components/schemas/ShippingMethodReferenceData", "description": "Shipping method reference" }, { "type": "null" } ], "description": "Shipping method reference" }, "freeShippingActive": { "description": "Free shipping active", "type": "boolean", "example": false }, "freeShippingFrom": { "description": "Free shipping from amount", "type": [ "number", "null" ], "format": "float", "example": 0 }, "ageCheckRequired": { "description": "Age check required", "type": "boolean", "example": false }, "deliveryTerms": { "description": "Delivery terms", "type": [ "string", "null" ], "example": "DAP" }, "deliveryBlock": { "description": "Delivery block", "type": "boolean", "example": false }, "deliveryBlockDate": { "description": "Delivery block date", "type": [ "string", "null" ], "format": "date", "example": "2025-06-10" }, "deliveryBlockReason": { "description": "Delivery block reason", "type": [ "string", "null" ], "example": "" }, "autoCreateDocuments": { "description": "Auto create documents setting", "type": "string", "enum": [ "deliveryNote", "invoice", "deliveryNoteAndInvoice" ], "example": "invoice" }, "orderQuoteRemarks": { "description": "Order quote remarks", "type": [ "string", "null" ], "example": "Standard delivery schedule – weekdays 08:00‑18:00" }, "commissionConsignmentWarehouse": { "oneOf": [ { "$ref": "#/components/schemas/StorageLocationReferenceData", "description": "Consignment storage location" }, { "type": "null" } ], "description": "Consignment storage location" } }, "type": "object" }, "Group": { "description": "Group object", "properties": { "id": { "description": "ID of group", "type": "string", "example": "4" }, "name": { "description": "Name of the group", "type": [ "string", "null" ], "example": "Wholesale" } }, "type": "object", "example": { "id": "4", "name": "Wholesale" }, "additionalProperties": false }, "GroupReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "Group ID", "type": "string", "example": "8" } }, "type": "object" }, "PaymentMethodReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the payment method", "type": "string", "example": "13" } }, "type": "object" }, "PostalAddress": { "description": "Represents a postal address with contact information.", "required": [ "name" ], "properties": { "name": { "description": "Represents an address consisting of a physical address and contact information.\nIt is used in various documents, such as invoices, delivery notes, etc.", "type": "string", "example": "John" }, "type": { "type": [ "string", "null" ], "enum": [ "mrs", "mr", "company", "other" ], "example": "mr" }, "title": { "type": [ "string", "null" ], "example": "Ms." }, "contactPerson": { "type": [ "string", "null" ], "example": "Laura Schneider" }, "department": { "type": [ "string", "null" ], "example": "Research & Development" }, "subDepartment": { "type": [ "string", "null" ], "example": "AI Lab" }, "addressSupplement": { "type": [ "string", "null" ], "example": "Gebäude B, 4. Etage" }, "street": { "type": [ "string", "null" ], "example": "Fuggerstraße 11" }, "zipCode": { "type": [ "string", "null" ], "example": "86150" }, "city": { "type": [ "string", "null" ], "example": "Augsburg" }, "state": { "type": [ "string", "null" ], "example": "BY" }, "country": { "type": [ "string", "null" ], "example": "DE" }, "salutation": { "type": [ "string", "null" ], "example": "Sehr geehrte Damen und Herren" }, "gln": { "type": [ "string", "null" ], "example": "1234567890123" }, "email": { "type": [ "string", "null" ], "example": "laura.schneider@xentral.com" }, "phone": { "type": [ "string", "null" ], "example": "+1-234-567-8900" }, "fax": { "type": [ "string", "null" ], "example": "+1-234-567-8901" }, "mobile": { "type": [ "string", "null" ], "example": "+1-234-567-8902" } }, "type": "object", "example": { "name": "John", "type": "mr", "title": "Ms.", "contactPerson": "Laura Schneider", "department": "Research & Development", "subDepartment": "CAI Lab", "addressSupplement": "Gebäude B, 4. Etage", "street": "Fuggerstraße 11", "zipCode": "86150", "city": "Augsburg", "state": "BY", "country": "DE", "salutation": "Sehr geehrte Damen und Herren", "gln": "1234567890123", "email": "alice@example.com", "phone": "+1-234-567-8900", "fax": "+1-234-567-8901", "mobile": "+1-234-567-8902" }, "additionalProperties": false }, "PrimaryBankAccountData": { "properties": { "bankName": { "description": "Bank name", "type": [ "string", "null" ], "example": "Commerzbank AG" }, "accountHolder": { "description": "Account holder name", "type": [ "string", "null" ], "example": "Xentral ERP Solutions GmbH" }, "iban": { "description": "IBAN", "type": [ "string", "null" ], "example": "DE12500105170648489890" }, "bic": { "description": "BIC/SWIFT code", "type": [ "string", "null" ], "example": "COBADEFFXXX" }, "sepa": { "$ref": "#/components/schemas/SepaData", "description": "SEPA mandate information" } }, "type": "object" }, "ProjectReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the project", "type": "string", "example": "13" } }, "type": "object" }, "SalesChannelReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the sales channel", "type": "string", "example": "1" } }, "type": "object" }, "SalesManagerData": { "required": [ "id" ], "properties": { "id": { "description": "Sales manager ID", "type": "string", "example": "447" }, "commission": { "description": "Commission percentage", "type": [ "number", "null" ], "format": "float", "example": 4.5 } }, "type": "object" }, "SepaData": { "properties": { "isCompanySepa": { "description": "Is company SEPA mandate", "type": "boolean", "example": true }, "mandateReference": { "description": "SEPA mandate reference", "type": [ "string", "null" ], "example": "TN2025DE9876543210XYZ" }, "mandateReferenceChange": { "description": "Mandate reference change flag", "type": "boolean", "example": false }, "mandateReferenceDate": { "description": "Mandate reference date", "type": [ "string", "null" ], "format": "date", "example": "2025-03-01" }, "usage": { "description": "SEPA mandate usage type", "type": "string", "enum": [ "single", "recurring" ], "example": "recurring" }, "isInitialMandate": { "description": "Is initial mandate", "type": "boolean", "example": true }, "remark": { "description": "SEPA mandate remark", "type": [ "string", "null" ], "example": "Standard SEPA mandate for monthly invoice settlement" } }, "type": "object" }, "ShippingMethodReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the shipping method", "type": "string", "example": "13" } }, "type": "object" }, "StorageLocationReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the storage location", "type": "string", "example": "13" } }, "type": "object" }, "Tag": { "description": "A tag (label) assigned to a resource.", "required": [ "id" ], "properties": { "id": { "description": "Tag ID.", "type": "string", "pattern": "[0-9]+", "example": "4" }, "title": { "description": "Display name of the tag.", "type": "string", "example": "important" }, "color": { "description": "Hex color code of the tag.", "type": "string", "example": "#FFFFFF" } }, "type": "object", "additionalProperties": false }, "TagReferenceData": { "description": "References an existing tag by `id` or names a tag by `title`, which is created if it does not exist; exactly one of the two.", "properties": { "id": { "description": "ID of an existing tag to assign. Unlike `title`, an unknown id never creates a tag.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "title": { "description": "Title of the Tag. A tag with this title is created if none exists.", "type": "string", "example": "important" } }, "type": "object", "oneOf": [ { "required": [ "id" ] }, { "required": [ "title" ] } ] }, "TaxData": { "properties": { "vatId": { "description": "VAT ID", "type": [ "string", "null" ], "example": "DE112233445" }, "taxNumber": { "description": "Tax number", "type": [ "string", "null" ], "example": "HRB 98765" }, "taxation": { "description": "Taxation type", "type": "string", "enum": [ "domestic", "eu", "export", "exempt" ], "example": "eu" }, "taxDisplay": { "description": "Tax display preference", "type": "string", "enum": [ "automatic", "net", "gross" ], "example": "gross" }, "useDeliveryThreshold": { "description": "Use delivery threshold", "type": "boolean", "example": true }, "customsInformation": { "description": "Customs information", "type": [ "string", "null" ], "example": "HS‑Code 8542.31 – Integrated circuits, origin DE, duty‑free under EU‑US agreement" } }, "type": "object" }, "TimestampsResource": { "properties": { "createdAt": { "description": "The date and time when the resource was created.", "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z" }, "updatedAt": { "description": "The date and time when the resource was last updated.", "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z" } }, "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Customer", "description": "Customer" } ], "paths": { "/api/v3/customers": { "post": { "tags": [ "Customer" ], "summary": "🔒 Create customer V3", "description": "This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues.\n\nThis endpoint requires the following scopes: `customer:create`.\n\nCreate a new customer.", "operationId": "POST::api-v3-customers", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerData" } } } }, "responses": { "201": { "description": "Create a new customer.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "type": "object" } } } }, "400": { "description": "Failed validation", "content": { "application/problem+json": { "schema": { "properties": { "type": { "description": "Error messages", "type": "string", "example": "https://api.xentral.biz/problems/request-validation" }, "title": { "description": "Error messages", "type": "string", "example": "Request payload validation failed." }, "violations": { "description": "Error messages", "type": "object", "example": { "number": [ "The number field must be a string." ], "deviatingDebtorAccountNumber": [ "The deviating debtor account number field must be a string." ], "routingId": [ "The routing id field must be a string." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Too Many Requests", "type": "string", "example": "Too Many Requests" } }, "type": "object" } } } } }, "x-beta": true, "x-scopes": [ "customer:create" ] } } } } ```