Xentral Customer API
Customer represents an information related to company, or individual person.
OpenAPI Specification
openapi: 3.0.0
info:
title: Xentral Account Customer API
version: v0.1
description: Xentral is an ERP platform.
contact:
name: Xentral
url: https://xentral.com
email: api@xentral.com
servers:
- url: https://{xentralId}.xentral.biz
description: Your Xentral Instance
variables:
xentralId:
default: xentral
- url: https://{domain}
description: Xentral at a custom domain
variables:
domain:
default: xentral.com
security:
- BearerAuth: []
tags:
- name: Customer
description: Customer represents an information related to company, or individual person.
paths:
/api/v1/customers/{id}:
delete:
tags:
- Customer
operationId: customer.delete
summary: Delete customer
description: Delete existing customer
parameters:
- in: path
name: id
required: true
description: The resource's identifier.
schema:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
responses:
'204':
description: Operation completed successfully, no response body
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'404':
description: Resource was not found or not enough access privileges
'415':
description: Resource representation send in the request is not supported.
/api/v2/customers:
get:
tags:
- Customer
operationId: customer.list.v2
summary: List customers
description: Fetches a list of customers based on provided filters and pagination parameters. This endpoint supports filtering by various customer attributes, as well as cursor and page-based pagination for efficient data retrieval.
parameters:
- name: filter
in: query
style: deepObject
schema:
anyOf:
- type: array
items:
type: object
additionalProperties: false
properties:
key:
type: string
enum:
- id
- uuid
- number
- customerType
- name
- deviatingCustomerNumber
- firstname
- lastname
- title
- salutation
- birthdate
- department
- subDepartment
- projectId
- phone
- fax
- email
- website
- salesManager
- accountManager
- isLead
- contactPerson
- street
- zip
- city
- state
- addressType
op:
type: string
enum:
- equals
- notEquals
- lessThan
- greaterThan
- in
- notIn
value:
oneOf:
- type: string
- type: array
items:
type: string
- name: page
in: query
style: deepObject
description: Page-based pagination (Default). Use this or `cursor`, but not both. If both are provided, an exception will be thrown.
schema:
type: object
additionalProperties: false
required:
- number
- size
properties:
number:
type: string
pattern: \d+
description: Page number should be an integer greater than or equal to 1
size:
type: string
pattern: \d+
description: Page size should usually be an integer between 10 and 50.
- name: cursor
in: query
description: Cursor-based pagination. Use this or `page`, but not both. If both are provided, an exception will be thrown.
schema:
type: object
additionalProperties: false
properties:
nextCursor:
type: string
description: nextCursor should be base64 encoded string returned from api
size:
type: string
pattern: \d+
description: Page size should usually be an integer between 10 and 50.
- name: order
in: query
style: deepObject
schema:
type: array
items:
type: object
additionalProperties: false
properties:
field:
type: string
enum:
- id
dir:
type: string
enum:
- asc
- desc
responses:
'200':
description: List of contact persons
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
properties:
data:
type: array
items:
type: object
additionalProperties: false
required:
- id
- number
- deviatingCustomerNumber
- customerType
- name
- firstname
- lastname
- salutation
- department
- subDepartment
- projects
- accountManager
- salesManager
- contactDetails
- isLead
- contactPerson
- documentDelivery
description: Customer object
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
uuid:
description: Nullable UUID identifier of the resource.
type: string
pattern: ^$|^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$
example: a00fd11e-3a67-433b-83c0-4e815fd4a0e1
nullable: true
number:
type: string
description: Customer number. if this is not provided default number ranges will be applied automatically
example: C700001
deviatingCustomerNumber:
type: string
description: Deviating Customer number.
example: C711223
customerType:
type: string
enum:
- company
- person
nullable: true
example: company
description: Type of customer
name:
type: string
nullable: false
example: Firstname Surname
description: Full name of the customer
firstname:
type: string
example: Firstname
description: First name of the customer
lastname:
type: string
example: Surname
description: Last name of the customer
title:
type: string
nullable: true
example: Prof. Dr.
description: Additional information used for salutations
salutation:
type: string
enum:
- company
- mr
- mrs
- other
nullable: true
example: mr
description: Salutation of the customer
birthdate:
type: string
format: date
nullable: true
description: Birthdate of customer
example: '2024-03-01'
department:
type: string
nullable: true
example: HR department
description: Department of customer if necessary and available
subDepartment:
type: string
nullable: true
example: Sub department
description: Sub-Department of customer if necessary and available
projects:
type: array
description: List of projects the customer should belong to
items:
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
contactDetails:
type: object
additionalProperties: false
description: Contact information of a customer
properties:
phone:
type: string
nullable: true
description: Phone number of a customer
example: +49(30)12093756
fax:
type: string
nullable: true
description: Fax number of a customer
example: +49(30)12093756-1
email:
type: string
nullable: true
description: Email address of a customer
example: customer@domain.tpl
website:
type: string
nullable: true
description: URL of customers website
example: http://company.tpl/members/max.mustermann
additionalData:
type: array
description: List of additional not default contact data
items:
type: object
additionalProperties: false
nullable: true
required:
- label
- value
properties:
label:
type: string
description: Specific key for customer contact data
example: mobile2
value:
type: string
nullable: true
description: Value for specified customers contact data key
example: +1(800)555 12235
example:
phone: +49 123 4567890
fax: +49 123 4567890-1
email: name@provider.com
website: http://my.website.tld
additionalData:
- label: Skype
value: max.mustermann
accountManager:
nullable: true
type: object
additionalProperties: false
required:
- id
description: Account manager of this customer
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
example:
id: '12345'
salesManager:
nullable: true
type: object
additionalProperties: false
required:
- id
description: Sales manager of this customer
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
example:
id: '12345'
isLead:
type: boolean
description: Tells if customer is a lead
example: true
contactPerson:
type: string
nullable: true
example: Milo Thatch
description: Name of contact person
documentDelivery:
type: object
description: Additional E-Mail addresses used for deliver business letters
additionalProperties: false
required:
- offer
- salesOrder
- invoice
- creditNote
- deliveryNote
- purchaseOrder
- dunning
properties:
offer:
type: object
x-description-missing: true
additionalProperties: false
properties:
email:
type: string
nullable: true
description: E-mail address used for sending document
example: customer@domain.tpl
cc:
type: string
nullable: true
description: E-mail address used for sending copy of document
example: customers-cc@otherdomain.tpl
salesOrder:
type: object
x-description-missing: true
additionalProperties: false
properties:
email:
type: string
nullable: true
description: E-mail address used for sending document
example: customer@domain.tpl
cc:
type: string
nullable: true
description: E-mail address used for sending copy of document
example: customers-cc@otherdomain.tpl
invoice:
type: object
x-description-missing: true
additionalProperties: false
properties:
email:
type: string
nullable: true
description: E-mail address used for sending document
example: customer@domain.tpl
cc:
type: string
nullable: true
description: E-mail address used for sending copy of document
example: customers-cc@otherdomain.tpl
creditNote:
type: object
x-description-missing: true
additionalProperties: false
properties:
email:
type: string
nullable: true
description: E-mail address used for sending document
example: customer@domain.tpl
cc:
type: string
nullable: true
description: E-mail address used for sending copy of document
example: customers-cc@otherdomain.tpl
deliveryNote:
type: object
x-description-missing: true
additionalProperties: false
properties:
email:
type: string
nullable: true
description: E-mail address used for sending document
example: customer@domain.tpl
cc:
type: string
nullable: true
description: E-mail address used for sending copy of document
example: customers-cc@otherdomain.tpl
purchaseOrder:
type: object
x-description-missing: true
additionalProperties: false
properties:
email:
type: string
nullable: true
description: E-mail address used for sending document
example: customer@domain.tpl
cc:
type: string
nullable: true
description: E-mail address used for sending copy of document
example: customers-cc@otherdomain.tpl
dunning:
type: object
x-description-missing: true
additionalProperties: false
properties:
email:
type: string
nullable: true
description: E-mail address used for sending document
example: customer@domain.tpl
cc:
type: string
nullable: true
description: E-mail address used for sending copy of document
example: customers-cc@otherdomain.tpl
autoCreateDocuments:
type: string
enum:
- both
- delivery_note
- invoice
description: Create receipts in auto-shipping
example: both
invoiceAlwaysPaper:
type: boolean
description: Even with automatic dispatch, a paper invoice is always created
example: true
amountInvoicePrints:
type: integer
nullable: true
description: Number of printouts during shipping
example: 2
preferFax:
type: boolean
description: Prefer sending by FAX
example: true
example:
offer:
email: offer-send@domain.tpl
cc: offer-send-cc@otherdomain.tpl
salesOrder:
email: salesOrder-send@domain.tpl
cc: salesOrder-send-cc@otherdomain.tpl
invoice:
email: invoice-send@domain.tpl
cc: invoice-send-cc@otherdomain.tpl
creditNote:
email: creditNote-send@domain.tpl
cc: creditNote-send-cc@otherdomain.tpl
deliveryNote:
email: deliveryNote-send@domain.tpl
cc: deliveryNote-send-cc@otherdomain.tpl
purchaseOrder:
email: purchaseOrder-send@domain.tpl
cc: purchaseOrder-send-cc@otherdomain.tpl
dunning:
email: dunning-send@domain.tpl
cc: dunning-send-cc@otherdomain.tpl
example:
id: '17'
uuid: a00fd11e-3a67-433b-83c0-4e815fd4a0e1
number: '700001'
deviatingCustomerNumber: '711223'
customerType: person
name: Sample Company ltd.
firstname: Max
lastname: Mustermann
title: Prof. Dr.
salutation: mr
birthdate: '1970-01-01'
department: Sales
subDepartment: Online Sales
projects:
- id: '1337'
- id: '1336'
contactDetails:
phone: +49 123 4567890
fax: +49 123 4567890-1
email: name@provider.com
website: http://my.website.tld
additionalData:
- label: Skype
value: max.mustermann
accountManager:
id: '321'
salesManager:
id: '245'
isLead: true
contactPerson: Milo Thatch
documentDelivery:
offer:
email: offer-send@domain.tpl
cc: offer-send-cc@otherdomain.tpl
salesOrder:
email: salesOrder-send@domain.tpl
cc: salesOrder-send-cc@otherdomain.tpl
invoice:
email: invoice-send@domain.tpl
cc: invoice-send-cc@otherdomain.tpl
creditNote:
email: creditNote-send@domain.tpl
cc: creditNote-send-cc@otherdomain.tpl
deliveryNote:
email: deliveryNote-send@domain.tpl
cc: deliveryNote-send-cc@otherdomain.tpl
purchaseOrder:
email: purchaseOrder-send@domain.tpl
cc: purchaseOrder-send-cc@otherdomain.tpl
dunning:
email: dunning-send@domain.tpl
cc: dunning-send-cc@otherdomain.tpl
extra:
oneOf:
- type: object
required:
- totalCount
- page
additionalProperties: false
x-description-ignore: true
properties:
totalCount:
description: the total count of all items
type: integer
example: 1
page:
description: The pagination object containing the current page number and size
type: object
required:
- number
- size
additionalProperties: false
properties:
number:
description: The current page number
type: integer
example: 1
size:
description: The size of the pages
type: integer
example: 10
example:
number: 1
size: 10
example:
totalCount: 1
page:
number: 1
size: 10
- type: object
required:
- totalCount
- cursor
additionalProperties: false
x-description-ignore: true
properties:
totalCount:
description: the total count of all items
type: integer
nullable: true
example: 1
cursor:
description: The pagination object containing the current page number and size
type: object
required:
- nextCursor
- size
additionalProperties: false
properties:
nextCursor:
description: Cursoer to use for next page request
type: string
example: NDI=
size:
description: The size of the pages
type: integer
example: 10
example:
nextCursor: MTA=
size: 10
example:
totalCount: 100
cursor:
nextCursor: MTA=
size: 10
'400':
description: IETF RFC 9457 Problem API compliant response
content:
application/problem+json:
schema:
oneOf:
- type: object
additionalProperties: false
required:
- type
- title
- violations
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/request-validation
title:
type: string
minLength: 1
example: Request payload validation failed.
violations:
oneOf:
- type: array
items:
type: object
example:
username:
- This value should not be blank.
email:
- This value is not a valid email address.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
example:
_:
- This value should contain at most `9` elements.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflict
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- items
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflictItems
title:
type: string
minLength: 1
items:
# --- truncated at 32 KB (517 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xentral/refs/heads/main/openapi/xentral-customer-api-openapi.yml