---
title: Smart Routings — Contacts de routage
excerpt: Gérez les contacts de routage utilisés par Smart Routings et leurs champs personnalisés, et importez-les ou exportez-les en masse.
order: 11
---

Les contacts de routage forment l'annuaire que Smart Routings utilise pour reconnaître un appelant et l'orienter vers une destination dédiée. Consultez [Smart Routings](/fr/docs/cx-api/smart-routings) pour les notions communes à tous les endpoints Smart Routings.

Tous les endpoints de cette section sont **propres à l'espace de travail** et nécessitent le scope OAuth `client`.

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

**Paramètre de requête obligatoire :** `customer_account` — le compte client concerné. Voir [Choix du compte client](/fr/docs/cx-api/smart-routings#choix-du-compte-client).

| Permission | Nécessaire pour |
|---|---|
| `routing-contact.view` | Lire et exporter les contacts |
| `routing-contact.create` | Créer, importer et supprimer en masse des contacts |
| `routing-contact.edit` | Modifier des contacts |
| `routing-contact.delete` | Supprimer un contact |
| `routing-contact-field-definition.view` | Lire les définitions de champs et leurs options |
| `routing-contact-field-definition.create` | Créer des définitions de champs |
| `routing-contact-field-definition.edit` | Modifier des définitions de champs et gérer leurs options |

---

## Contacts de routage

### L'objet contact

| Champ | Type | Description |
|---|---|---|
| `id` | integer | ID du contact |
| `customer_id` | integer | Client auquel appartient le contact |
| `id_code` | string\|null | Votre propre identifiant pour ce contact |
| `language_code` | string\|null | Code de langue du contact |
| `company` | string\|null | Nom de l'entreprise |
| `first_name` | string\|null | Prénom |
| `last_name` | string\|null | Nom |
| `emails` | string\|null | Adresse(s) e-mail servant à reconnaître le contact |
| `telecoms` | string\|null | Numéro(s) de téléphone servant à reconnaître le contact |
| `email_destination` | string\|null | Destination e-mail de ce contact |
| `telecom_destination` | string\|null | Destination téléphonique de ce contact |
| `fields` | array | Valeurs des champs personnalisés (voir ci-dessous) |
| `created_at` | string | Date de création (ISO 8601) |
| `updated_at` | string | Date de dernière modification (ISO 8601) |

Chaque entrée de `fields` contient sa valeur et sa définition, ce qui évite une seconde requête pour obtenir les libellés :

| Champ | Type | Description |
|---|---|---|
| `code` | string | Code de la définition de champ |
| `label` | string\|null | Libellé de la définition de champ |
| `type` | string | `telecom`, `email`, `boolean` ou `select` |
| `value` | string | Valeur enregistrée |
| `options` | array\|null | Pour les champs `select`, les options disponibles sous forme de paires `{ "name", "value" }` ; `null` sinon |

---

### GET /api/smart-routings/contacts

Renvoie la liste paginée des contacts de routage du client, du plus récent au plus ancien.

**Paramètres de requête**

| Paramètre | Description |
|---|---|
| `filter[id_code]` | Filtrer par code d'identification (correspondance partielle) |
| `filter[company]` | Filtrer par entreprise (correspondance partielle) |
| `filter[first_name]` | Filtrer par prénom (correspondance partielle) |
| `filter[last_name]` | Filtrer par nom (correspondance partielle) |
| `filter[emails]` | Filtrer par e-mails (correspondance partielle) |
| `filter[telecoms]` | Filtrer par numéros de téléphone (correspondance partielle) |
| `filter[telecom_destination]` | Filtrer par destination téléphonique (correspondance exacte) |
| `filter[language_code]` | Filtrer par code de langue (correspondance exacte) |
| `filter[search]` | Rechercher dans l'entreprise, le prénom, le nom, les numéros, la destination téléphonique et la destination e-mail |
| `sort` | Champ de tri : `id`, `company`, `first_name`, `last_name`, `created_at`. Préfixez par `-` pour un tri décroissant. Par défaut : `-created_at` |
| `per_page` | Nombre de résultats par page (20 par défaut) |
| `page` | Numéro de page |

**Réponse `200`** — réponse paginée

```json
{
  "data": [
    {
      "id": 57,
      "customer_id": 12,
      "id_code": "CUST-0042",
      "language_code": "fr",
      "company": "Acme Corp",
      "first_name": "Alice",
      "last_name": "Martin",
      "emails": "alice.martin@acme.com",
      "telecoms": "+33612345678",
      "email_destination": null,
      "telecom_destination": "201",
      "created_at": "2024-05-02T14:20:00.000000Z",
      "updated_at": "2024-05-02T14:20:00.000000Z",
      "fields": [
        {
          "code": "vip",
          "label": "VIP",
          "type": "boolean",
          "value": "1",
          "options": null
        },
        {
          "code": "segment",
          "label": "Segment",
          "type": "select",
          "value": "gold",
          "options": [
            { "name": "Gold", "value": "gold" },
            { "name": "Silver", "value": "silver" }
          ]
        }
      ]
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}
```

---

### GET /api/smart-routings/contacts/{contact}

Renvoie un contact de routage avec ses `fields`.

**Réponse `200`** — objet contact

**Réponse `403`** — le contact appartient à un autre client ou la permission est manquante

---

### POST /api/smart-routings/contacts

Crée un contact de routage.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id_code` | string | non | Votre propre identifiant pour ce contact |
| `language_code` | string | non | Code de langue |
| `company` | string | non | Nom de l'entreprise |
| `first_name` | string | non | Prénom |
| `last_name` | string | non | Nom |
| `emails` | string | non | Adresse(s) e-mail |
| `telecoms` | string | non | Numéro(s) de téléphone |
| `email_destination` | string | non | Destination e-mail |
| `telecom_destination` | string | non | Destination téléphonique |
| `fields` | array | non | Valeurs des champs personnalisés |
| `fields[].code` | string | oui | Code de la définition de champ (lettres, chiffres, `-` et `_` uniquement) |
| `fields[].value` | string | oui | Valeur à enregistrer |
| `fields[].type` | string | non | `telecom` ou `email`. Utilisé uniquement si le code n'existe pas encore (voir ci-dessous) |

Lorsqu'une entrée de `fields` fait référence à un code sans définition de champ :

- si `type` vaut `telecom` ou `email`, la définition est créée automatiquement ;
- sinon la requête échoue avec une erreur `422`. Les champs `boolean` et `select` doivent d'abord être créés via les endpoints des [définitions de champs](#définitions-de-champs).

**Exemple**

```json
{
  "company": "Acme Corp",
  "first_name": "Alice",
  "last_name": "Martin",
  "telecoms": "+33612345678",
  "telecom_destination": "201",
  "fields": [
    { "code": "segment", "value": "gold" },
    { "code": "backup_line", "value": "+33142000000", "type": "telecom" }
  ]
}
```

**Réponse `201`** — l'objet contact créé, avec ses `fields`

**Réponse `422`** — code de champ `boolean` ou `select` inconnu

```json
{
  "response": "Unknown field code \"vip\". Boolean/select fields must be created via the field-definition endpoint first.",
  "hint": null
}
```

---

### PUT /api/smart-routings/contacts/{contact}

Modifie un contact de routage. `PATCH` est également accepté. Accepte les mêmes champs qu'à la création, tous facultatifs.

Les valeurs envoyées dans `fields` sont créées ou remplacées une par une ; les champs personnalisés non envoyés conservent leur valeur actuelle.

**Réponse `201`** — l'objet contact modifié, avec ses `fields`

---

### DELETE /api/smart-routings/contacts/{contact}

Supprime un contact de routage.

**Réponse `200`**

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

---

## Opérations en masse

### GET /api/smart-routings/contacts/export

Télécharge les contacts de routage du client sous forme de fichier Excel (`routing_contacts.xlsx`), triés par entreprise.

Le fichier contient les colonnes `id`, `id_code`, `language_code`, `company`, `first_name`, `last_name`, `emails`, `telecoms`, `email_destination` et `telecom_destination`, suivies d'une colonne par [définition de champ](#définitions-de-champs) du client (active ou non), triées par `position` et intitulées avec le `code` de la définition. Chaque cellule contient la valeur du contact pour ce champ, ou reste vide. Toutes les cellules sont écrites en texte : les numéros de téléphone gardent leur `+` ou leur `0` initial.

| id | company | telecoms | telecom_destination | vip | segment | destination2 |
|---|---|---|---|---|---|---|
| 12 | Acme | +33612345678 | 200 | 1 | gold | +33600000000 |

Une définition dont le `code` reprend le nom d'une colonne de base n'est pas exportée.

---

### POST /api/smart-routings/contacts/import

Importe des contacts de routage depuis un tableur. Envoyez la requête en `multipart/form-data`.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `customer_id` | integer | oui | ID du client. Doit correspondre au compte client sélectionné |
| `document` | file | oui | Tableur (Excel, ou CSV avec `;` comme séparateur) avec une ligne d'en-tête |

La ligne d'en-tête reprend les colonnes de l'export : partez d'un export pour construire le fichier.

- Une ligne avec un `id` existant met à jour ce contact ; une ligne sans `id` en crée un nouveau.
- Les lignes dont l'`id` appartient à un autre client sont ignorées.
- Les lignes sans aucune des valeurs `id_code`, `company`, `telecoms` ou `emails` sont ignorées.
- Une colonne intitulée avec le `code` d'une définition de champ renseigne ce champ personnalisé. Une cellule vide supprime la valeur du contact pour ce champ. Un champ sans colonne dans le fichier n'est pas modifié.
- Les colonnes qui ne correspondent à aucune définition de champ sont ignorées : créez d'abord les définitions.
- Les champs `boolean` acceptent `1`, `true`, `yes`, `oui` (enregistrés `1`) et `0`, `false`, `no`, `non` (enregistrés `0`).
- Les champs `select` acceptent la `value` d'une option, ou son `name`, enregistré sous sa valeur.

Tout le fichier est validé avant la moindre écriture. Si une ligne contient une valeur de champ personnalisé invalide, rien n'est importé et l'API répond `422`.

**Réponse `200`**

```json
{ "response": "Import successful." }
```

---

### DELETE /api/smart-routings/contacts/bulk

Supprime des contacts de routage en masse, ainsi que les valeurs de leurs champs personnalisés.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `ids` | integer[] | non | ID des contacts à supprimer |

> [!WARNING]
> Sans `ids`, **tous** les contacts de routage du client sont supprimés.

**Réponse `200`**

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

---

## Définitions de champs

Les définitions de champs décrivent les champs personnalisés disponibles sur les contacts de routage du client. Une définition ne peut pas être supprimée, car un flux d'appel peut encore faire référence à son `code` : passez `active` à `false` pour la masquer.

### L'objet définition de champ

| Champ | Type | Description |
|---|---|---|
| `id` | integer | ID de la définition |
| `customer_id` | integer | Client auquel appartient la définition |
| `code` | string | Code unique par client, utilisé dans les `fields` des contacts et dans les flux d'appel. Non modifiable |
| `label` | string\|null | Libellé affiché |
| `type` | string | `telecom`, `email`, `boolean` ou `select`. Non modifiable |
| `position` | integer | Ordre d'affichage |
| `active` | boolean | Indique si le champ est affiché dans le formulaire du contact |
| `options` | array | Options d'un champ `select` (chargées en liste et en détail) |
| `created_at` | string | Date de création (ISO 8601) |
| `updated_at` | string | Date de dernière modification (ISO 8601) |

---

### GET /api/smart-routings/contact-field-definitions

Renvoie la liste paginée des définitions de champs du client, avec leurs `options`, triées par `position`.

**Paramètres de requête**

| Paramètre | Description |
|---|---|
| `filter[code]` | Filtrer par code (correspondance partielle) |
| `filter[label]` | Filtrer par libellé (correspondance partielle) |
| `filter[type]` | Filtrer par type |
| `filter[active]` | Filtrer par état actif |
| `sort` | Champ de tri : `id`, `code`, `label`, `type`, `position`, `created_at`. Préfixez par `-` pour un tri décroissant. Par défaut : `position` |
| `per_page` | Nombre de résultats par page (20 par défaut) |
| `page` | Numéro de page |

**Réponse `200`** — réponse paginée

```json
{
  "data": [
    {
      "id": 3,
      "customer_id": 12,
      "code": "segment",
      "label": "Segment",
      "type": "select",
      "position": 1,
      "active": true,
      "created_at": "2024-05-01T09:00:00.000000Z",
      "updated_at": "2024-05-01T09:00:00.000000Z",
      "options": [
        {
          "id": 8,
          "routing_contact_field_definition_id": 3,
          "name": "Gold",
          "value": "gold",
          "created_at": "2024-05-01T09:01:00.000000Z",
          "updated_at": "2024-05-01T09:01:00.000000Z"
        }
      ]
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}
```

---

### GET /api/smart-routings/contact-field-definitions/{definition}

Renvoie une définition de champ avec ses `options`.

**Réponse `200`** — objet définition de champ

---

### POST /api/smart-routings/contact-field-definitions

Crée une définition de champ.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `code` | string | oui | Code unique (255 caractères max. ; lettres, chiffres, `-` et `_` uniquement) |
| `type` | string | oui | `telecom`, `email`, `boolean` ou `select` |
| `label` | string | non | Libellé affiché (255 caractères max.) |
| `position` | integer | non | Ordre d'affichage (0 min.). Par défaut, après la dernière définition |
| `active` | boolean | non | Indique si le champ est affiché dans le formulaire du contact |

**Réponse `201`** — l'objet définition de champ créé

---

### PUT /api/smart-routings/contact-field-definitions/{definition}

Modifie une définition de champ. `PATCH` est également accepté. `code` et `type` ne sont pas modifiables.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `label` | string | non | Libellé affiché (255 caractères max.) |
| `position` | integer | non | Ordre d'affichage (0 min.) |
| `active` | boolean | non | Indique si le champ est affiché dans le formulaire du contact |

**Réponse `201`** — l'objet définition de champ modifié

---

## Options de champ

Les options sont les valeurs autorisées d'une définition de champ `select`. Appeler ces endpoints sur une définition d'un autre type renvoie une erreur `422`.

```json
{ "response": "This field cannot have options.", "hint": null }
```

### GET /api/smart-routings/contact-field-definitions/{definition}/options

Renvoie toutes les options de la définition. Cette liste n'est pas paginée.

**Réponse `200`**

```json
[
  {
    "id": 8,
    "routing_contact_field_definition_id": 3,
    "name": "Gold",
    "value": "gold",
    "created_at": "2024-05-01T09:01:00.000000Z",
    "updated_at": "2024-05-01T09:01:00.000000Z"
  }
]
```

---

### GET /api/smart-routings/contact-field-definitions/{definition}/options/{option}

Renvoie une option.

**Réponse `200`** — objet option

**Réponse `403`** — l'option n'appartient pas à cette définition

---

### POST /api/smart-routings/contact-field-definitions/{definition}/options

Ajoute une option à une définition `select`.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | oui | Nom affiché (255 caractères max.) |
| `value` | string | oui | Valeur enregistrée (255 caractères max.) |

**Réponse `201`** — la liste complète et à jour des options de la définition

---

### PUT /api/smart-routings/contact-field-definitions/{definition}/options/{option}

Modifie une option. `PATCH` est également accepté.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | non | Nom affiché (255 caractères max.) |
| `value` | string | non | Valeur enregistrée (255 caractères max.) |

**Réponse `201`** — la liste complète et à jour des options de la définition

---

### DELETE /api/smart-routings/contact-field-definitions/{definition}/options/{option}

Supprime une option.

**Réponse `200`**

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