---
title: Customers
excerpt: List, create, update and delete the customer accounts of a workspace, resolve the account a credential targets, and set its regional settings.
order: 3
---

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

```json
{
  "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](/en/docs/cx-api/smart-routings#selecting-the-customer-account)).

---

## 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](/en/docs/cx-api/contacts) |
| `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

```json
{
  "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`**

```json
{ "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`**

```json
{
  "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

```json
{
  "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