---
title: Clients
excerpt: Listez, créez, modifiez et supprimez les comptes clients d'un workspace, identifiez le compte ciblé par un identifiant d'accès et définissez ses paramètres régionaux.
order: 3
---

Un **client** est un compte client final au sein de votre workspace. La plupart des ressources d'intégration (clés d'intégration CRM, historique des appels, Smart Routings…) appartiennent à un client.

Tous les endpoints de cette section sont **scopés au workspace**.

**En-têtes :** `Authorization: Bearer {token-workspace}`

---

## Permissions

| Endpoint | Condition |
|---|---|
| `GET /api/customers` | Utilisateur admin avec la permission `customer.view` |
| `GET /api/customers/{id}` | Permission `customer.view`, ou utilisateur contact de ce client |
| `POST /api/customers` | Utilisateur admin avec la permission `customer.create` |
| `PUT /api/customers/{id}` | Utilisateur admin avec la permission `customer.edit` |
| `DELETE /api/customers/{id}` | Utilisateur admin avec la permission `customer.delete` |
| `GET /api/customers/resolve` | Scope OAuth `client` + accès au compte client sélectionné |
| `PUT /api/customers/settings` | Scope OAuth `client` + utilisateur admin avec la permission `customer.edit` |

---

## L'objet client

```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` est le code de compte qui permet de cibler ce client sur les endpoints scopés au client (voir [Smart Routings](/fr/docs/cx-api/smart-routings#choix-du-compte-client)).

---

## GET /api/customers

Retourne tous les clients du workspace sous forme de tableau JSON simple (non paginé).

**Réponse `200`** : tableau d'objets client

---

## GET /api/customers/{id}

Retourne un client.

**Réponse `200`** : objet client

**Réponse `403`** : accès non autorisé

---

## POST /api/customers

Crée un client. Le corps doit être un objet JSON.

**Corps de la requête**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `name` | string | oui | Raison sociale (2 à 255 caractères) |
| `customer_account` | string | non | Code de compte (2 à 255 caractères) |
| `active` | boolean | non | Compte actif ou non |
| `registration_number` | string | non | Numéro d'immatriculation (SIRET…, 2 à 20 caractères) |
| `tax_registration_number` | string | non | Numéro de TVA (2 à 20 caractères) |
| `main_address_line_1` | string | non | Ligne d'adresse 1 |
| `main_address_line_2` | string | non | Ligne d'adresse 2 |
| `main_address_post_code` | string | non | Code postal |
| `main_address_city` | string | non | Ville |
| `main_address_country` | string | non | Pays |
| `email_address` | string | non | Adresse email principale |
| `account_email_address` | string | non | Adresse email de facturation |
| `phone` | string | non | Numéro de téléphone |
| `mobile_phone` | string | non | Numéro de mobile |
| `fax` | string | non | Numéro de fax |
| `website` | string | non | Site web |
| `type` | string | non | Type de client (texte libre) |
| `capital` | string | non | Capital social |
| `activity_code` | string | non | Code d'activité |
| `abroad` | boolean | non | Client basé à l'étranger |
| `zone` | integer | non | Numéro de zone |
| `main_contact_id` | integer | non | ID d'un [contact](/fr/docs/cx-api/contacts) existant |
| `representative_id` | integer | non | ID d'un utilisateur existant |
| `sector_id` | integer | non | ID du secteur |
| `origin_id` | integer | non | ID de l'origine |

`id`, `uuid`, `created_at` et `updated_at` ne peuvent pas être définis.

**Réponse `201`** : l'objet client créé

**Réponse `400`** : échec de validation

```json
{
  "response": "bad request: please check body parameters.",
  "hint": ["The name field is required."]
}
```

---

## PUT /api/customers/{id}

Modifie un client. Accepte les mêmes champs que `POST /api/customers`, tous facultatifs. Seuls les champs envoyés sont modifiés.

**Réponse `201`** : l'objet client modifié

---

## DELETE /api/customers/{id}

Supprime un client (suppression logique).

**Réponse `200`**

```json
{ "response": "element deleted" }
```

---

## GET /api/customers/resolve

Retourne le compte client ciblé par la requête. Utile pour vérifier qu'un identifiant d'accès et un `customer_account` désignent bien le client attendu avant d'appeler d'autres endpoints scopés au client.

Requiert le scope OAuth `client`.

**Paramètres de requête**

| Paramètre | Type | Requis | Description |
|---|---|---|---|
| `customer_account` | string | oui* | Code de compte client |
| `customer_id` | integer | oui* | ID du client |

*Fournir l'un des deux.

**Réponse `200`**

```json
{
  "response": "ok",
  "id": 12,
  "customer_account": "ACME01"
}
```

**Réponse `403`** : aucun client ne correspond aux paramètres, ou l'identifiant d'accès n'a pas accès à ce client

---

## PUT /api/customers/settings

Définit les paramètres régionaux généraux du client sélectionné. Requiert le scope OAuth `client`.

**Paramètres de requête**

| Paramètre | Type | Requis | Description |
|---|---|---|---|
| `customer_account` | string | oui* | Code de compte client |
| `customer_id` | integer | oui* | ID du client |

*Fournir l'un des deux.

**Corps de la requête** (objet JSON, tous les champs sont facultatifs, au moins un champ requis)

| Champ | Type | Requis | Description |
|---|---|---|---|
| `country` | string | non | Pays par défaut, code à 2 lettres (ex. `fr`) |
| `language` | string | non | Langue, code à 2 lettres (ex. `fr`) |
| `timezone` | string | non | Fuseau horaire valide (ex. `Europe/Paris`) |
| `date_format` | string | non | Format de date, 20 caractères max. (ex. `d/m/Y`) |

Le fuseau horaire est utilisé par les Smart Routings pour évaluer les plages horaires et les exceptions dans l'heure locale du client.

**Réponse `200`** : l'ensemble des paramètres généraux du client après la mise à jour

```json
{
  "response": "ok",
  "settings": {
    "general.default_country": "fr",
    "general.timezone": "Europe/Paris",
    "general.language": "fr",
    "general.date_format": "d/m/Y"
  }
}
```

**Réponse `400`** : échec de validation (ex. fuseau horaire inconnu)

**Réponse `403`** : aucun client ne correspond aux paramètres, ou accès non autorisé