A customer is an end-client account inside your workspace. Most integration resources (CRM integration keys, call history, Smart Routings…) belong to a customer.
All endpoints in this section are workspace-scoped.
Headers: Authorization: Bearer {workspace-token}
#Permissions
| Endpoint | Requirement |
|---|---|
GET /api/customers |
Admin user with the customer.view permission |
GET /api/customers/{id} |
customer.view permission, or a user who is a contact of that customer |
POST /api/customers |
Admin user with the customer.create permission |
PUT /api/customers/{id} |
Admin user with the customer.edit permission |
DELETE /api/customers/{id} |
Admin user with the customer.delete permission |
GET /api/customers/resolve |
client OAuth scope + access to the selected customer account |
PUT /api/customers/settings |
client OAuth scope + admin user with the customer.edit permission |
#The customer object
{
"id": 12,
"uuid": "3f0c6a51-8d0e-4b7e-a1c2-6f1f0b2d9e44",
"representative_id": null,
"main_contact_id": 41,
"active": true,
"name": "Acme Corp",
"registration_number": "12345678900012",
"tax_registration_number": "FR12345678900",
"main_address_line_1": "10 rue de la Paix",
"main_address_line_2": null,
"main_address_post_code": "75002",
"main_address_city": "Paris",
"main_address_country": "France",
"customer_account": "ACME01",
"email_address": "contact@acme.com",
"account_email_address": "billing@acme.com",
"fax": null,
"phone": "+33142000000",
"mobile_phone": null,
"website": "https://acme.com",
"logo": null,
"type": null,
"capital": null,
"activity_code": null,
"sector_id": null,
"origin_id": null,
"abroad": false,
"zone": 0,
"quick_search_label": null,
"quick_search_index": 0,
"deleted_at": null,
"created_at": "2024-03-01T09:00:00.000000Z",
"updated_at": "2024-06-12T14:30:00.000000Z"
}
customer_account is the account code used to target this customer on customer-scoped endpoints (see Smart Routings).
#GET /api/customers
Returns every customer of the workspace as a plain JSON array (not paginated).
Response 200 — array of customer objects
#GET /api/customers/{id}
Returns a single customer.
Response 200 — customer object
Response 403 — not authorized
#POST /api/customers
Creates a customer. The body must be a JSON object.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Company name (2–255 characters) |
customer_account |
string | no | Account code (2–255 characters) |
active |
boolean | no | Whether the account is active |
registration_number |
string | no | Company registration number (2–20 characters) |
tax_registration_number |
string | no | VAT number (2–20 characters) |
main_address_line_1 |
string | no | Address line 1 |
main_address_line_2 |
string | no | Address line 2 |
main_address_post_code |
string | no | Post code |
main_address_city |
string | no | City |
main_address_country |
string | no | Country |
email_address |
string | no | Main email address |
account_email_address |
string | no | Accounting email address |
phone |
string | no | Phone number |
mobile_phone |
string | no | Mobile phone number |
fax |
string | no | Fax number |
website |
string | no | Website |
type |
string | no | Free-form customer type |
capital |
string | no | Share capital |
activity_code |
string | no | Activity code |
abroad |
boolean | no | Whether the customer is based abroad |
zone |
integer | no | Zone number |
main_contact_id |
integer | no | ID of an existing contact |
representative_id |
integer | no | ID of an existing user |
sector_id |
integer | no | Sector ID |
origin_id |
integer | no | Origin ID |
id, uuid, created_at and updated_at cannot be set.
Response 201 — the created customer object
Response 400 — validation failure
{
"response": "bad request: please check body parameters.",
"hint": ["The name field is required."]
}
#PUT /api/customers/{id}
Updates a customer. Accepts the same fields as POST /api/customers, all optional. Only the fields you send are changed.
Response 201 — the updated customer object
#DELETE /api/customers/{id}
Deletes a customer (soft delete).
Response 200
{ "response": "element deleted" }
#GET /api/customers/resolve
Returns the customer account targeted by the request. Use it to check that a credential and a customer_account resolve to the expected customer before calling other customer-scoped endpoints.
Requires the client OAuth scope.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customer_account |
string | yes* | Customer account code |
customer_id |
integer | yes* | Customer ID |
*Provide one of the two.
Response 200
{
"response": "ok",
"id": 12,
"customer_account": "ACME01"
}
Response 403 — no customer matches the given parameters, or the credential has no access to it
#PUT /api/customers/settings
Sets the general regional settings of the selected customer. Requires the client OAuth scope.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customer_account |
string | yes* | Customer account code |
customer_id |
integer | yes* | Customer ID |
*Provide one of the two.
Request body (JSON object, all fields optional, at least one field required)
| Field | Type | Required | Description |
|---|---|---|---|
country |
string | no | Default country, 2-letter code (e.g. fr) |
language |
string | no | Language, 2-letter code (e.g. fr) |
timezone |
string | no | Valid timezone identifier (e.g. Europe/Paris) |
date_format |
string | no | Date format, max 20 characters (e.g. d/m/Y) |
The timezone is used by Smart Routings to evaluate time spans and exceptions in the customer's local time.
Response 200 — all general settings of the customer after the update
{
"response": "ok",
"settings": {
"general.default_country": "fr",
"general.timezone": "Europe/Paris",
"general.language": "fr",
"general.date_format": "d/m/Y"
}
}
Response 400 — validation failure (e.g. unknown timezone)
Response 403 — no customer matches the given parameters, or not authorized