---
title: Smart Routings — Routage géographique
excerpt: Gérez les listes de routage géographique et leurs destinations, consultez les modèles géographiques et trouvez la destination correspondant à la zone ou au numéro d'un appelant.
order: 12
---

Le routage géographique envoie un appel vers une destination choisie selon la zone géographique de l'appelant. 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`. L'endpoint de lookup accepte également le scope `cfd`.

**Headers :** `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 |
|---|---|
| `geo-routing-list.view` | Consulter les listes, les destinations et les modèles |
| `geo-routing-list.create` | Créer des listes |
| `geo-routing-list.edit` | Modifier les listes et créer, modifier ou supprimer des destinations |
| `geo-routing-list.delete` | Supprimer des listes |
| `geo-routing-list.lookup` | Rechercher une destination |

---

## Modèles géographiques

Un modèle géographique définit l'ensemble des zones sur lesquelles une liste peut router, et la façon dont un numéro de téléphone est associé à une zone. Les modèles sont communs à tous les clients de l'espace de travail et sont en lecture seule via l'API. Les modèles fournis couvrent notamment les départements français (zones `01` à `98`), les préfixes internationaux (codes ISO 3166-1 alpha-2) et les États membres de l'Union européenne.

### GET /api/smart-routings/geo/models

Renvoie la liste paginée des modèles géographiques.

**Paramètres de requête**

| Paramètre | Description |
|---|---|
| `per_page` | Nombre de résultats par page (par défaut : 20) |
| `page` | Numéro de page |

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

```json
{
  "data": [
    {
      "id": 1,
      "name": "French Districts",
      "created_at": "2024-01-15T09:30:00.000000Z",
      "updated_at": "2024-01-15T09:30:00.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 3
}
```

---

### GET /api/smart-routings/geo/models/{id}

Renvoie un modèle géographique, avec la liste des zones qu'il définit.

**Réponse `200`**

```json
{
  "id": 1,
  "name": "French Districts",
  "zones": ["01", "02", "03", "...", "98"],
  "created_at": "2024-01-15T09:30:00.000000Z",
  "updated_at": "2024-01-15T09:30:00.000000Z"
}
```

---

## Listes de routage géographique

Une liste associe un modèle géographique à un ensemble de destinations. Chaque liste possède un identifiant numérique `list_id`, unique par client, et jusqu'à quatre destinations de repli utilisées lorsqu'aucune destination ne couvre la zone de l'appelant.

### GET /api/smart-routings/geo/lists

Renvoie la liste paginée des listes de routage géographique du client. Chaque liste inclut l'`id` et le `name` de son modèle.

**Paramètres de requête**

| Paramètre | Description |
|---|---|
| `filter[list_id]` | Filtrer par identifiant de liste |
| `filter[list_name]` | Filtrer par nom de liste |
| `filter[geo_routing_model_id]` | Filtrer par identifiant de modèle géographique (correspondance exacte) |
| `sort` | Champ de tri : `id`, `list_id`, `list_name`, `created_at`. Préfixez par `-` pour un tri décroissant. Par défaut : `list_id`, puis `list_name` |
| `per_page` | Nombre de résultats par page (par défaut : 20) |
| `page` | Numéro de page |

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

```json
{
  "data": [
    {
      "id": 4,
      "customer_id": 12,
      "geo_routing_model_id": 1,
      "list_id": 1,
      "list_name": "Sales France",
      "fallback_destination_1": "100",
      "fallback_destination_2": null,
      "fallback_destination_3": null,
      "fallback_destination_4": null,
      "created_at": "2024-03-02T10:00:00.000000Z",
      "updated_at": "2024-03-02T10:00:00.000000Z",
      "model": { "id": 1, "name": "French Districts" }
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}
```

---

### GET /api/smart-routings/geo/lists/{id}

Renvoie une liste avec son modèle géographique complet et `orphan_zones` : les zones du modèle qu'aucune destination de la liste ne couvre encore.

**Réponse `200`**

```json
{
  "id": 4,
  "customer_id": 12,
  "geo_routing_model_id": 1,
  "list_id": 1,
  "list_name": "Sales France",
  "fallback_destination_1": "100",
  "fallback_destination_2": null,
  "fallback_destination_3": null,
  "fallback_destination_4": null,
  "created_at": "2024-03-02T10:00:00.000000Z",
  "updated_at": "2024-03-02T10:00:00.000000Z",
  "orphan_zones": ["01", "02", "04"],
  "model": {
    "id": 1,
    "name": "French Districts",
    "zones": ["01", "02", "03", "...", "98"],
    "created_at": "2024-01-15T09:30:00.000000Z",
    "updated_at": "2024-01-15T09:30:00.000000Z"
  }
}
```

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

---

### POST /api/smart-routings/geo/lists

Crée une liste de routage géographique pour le client.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `list_name` | string | oui | Nom de la liste (50 caractères max.) |
| `geo_routing_model_id` | integer | oui | Identifiant d'un modèle géographique existant |
| `list_id` | integer | non | Identifiant numérique de la liste, unique par client. S'il est omis, le prochain numéro disponible est attribué |
| `fallback_destination_1` | string | non | Première destination de repli (255 caractères max.) |
| `fallback_destination_2` | string | non | Deuxième destination de repli |
| `fallback_destination_3` | string | non | Troisième destination de repli |
| `fallback_destination_4` | string | non | Quatrième destination de repli |

**Réponse `201`** — la liste créée

**Réponse `400`** — erreur de validation, ou une autre liste du client utilise déjà ce `list_id`

```json
{
  "response": "bad request: please check body parameters.",
  "hint": ["Another list with the same list_id exists."]
}
```

---

### PUT /api/smart-routings/geo/lists/{id}

Met à jour une liste. Tous les champs de l'endpoint de création sont acceptés et facultatifs. `PATCH` est également accepté.

Lorsque `list_id` est omis (ou `null`), la liste conserve son `list_id` actuel. Envoyez-le uniquement pour renuméroter la liste.

**Réponse `201`** — la liste mise à jour

**Réponse `400`** — erreur de validation, ou une autre liste du client utilise déjà ce `list_id`

---

### DELETE /api/smart-routings/geo/lists/{id}

Supprime une liste ainsi que toutes ses destinations.

**Réponse `200`**

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

---

## Destinations d'une liste

Une destination associe une ou plusieurs zones du modèle de la liste à un maximum de quatre destinations. Une zone ne peut appartenir qu'à une seule destination d'une liste.

### GET /api/smart-routings/geo/lists/{list}/destinations

Renvoie toutes les destinations de la liste (sans pagination).

**Réponse `200`**

```json
[
  {
    "id": 21,
    "geo_routing_list_id": 4,
    "nickname": "Paris area",
    "zones": ["75", "77", "78", "91", "92", "93", "94", "95"],
    "destination_1": "201",
    "destination_2": "202",
    "destination_3": null,
    "destination_4": null,
    "created_at": "2024-03-02T10:05:00.000000Z",
    "updated_at": "2024-03-02T10:05:00.000000Z"
  }
]
```

---

### GET /api/smart-routings/geo/lists/{list}/destinations/{id}

Renvoie une destination.

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

**Réponse `404`** — la destination n'appartient pas à cette liste

---

### POST /api/smart-routings/geo/lists/{list}/destinations

Ajoute une destination à la liste.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `zones` | array | oui | Au moins une zone. Chaque zone doit exister dans le modèle géographique de la liste et ne pas être déjà utilisée par une autre destination de la liste |
| `nickname` | string | non | Nom d'affichage (255 caractères max.) |
| `destination_1` | string | non | Première destination (255 caractères max.) |
| `destination_2` | string | non | Deuxième destination |
| `destination_3` | string | non | Troisième destination |
| `destination_4` | string | non | Quatrième destination |

**Réponse `201`** — la destination créée

**Réponse `400`** — erreur de validation, ou zones invalides. Le message indique les zones en cause :

- `Some selected zones are unknown to the selected model (99).`
- `Some selected zones are already used (75, 92).`

---

### PUT /api/smart-routings/geo/lists/{list}/destinations/{id}

Met à jour une destination. Tous les champs de l'endpoint de création sont acceptés et facultatifs ; les zones sont contrôlées de la même façon. `PATCH` est également accepté.

**Réponse `201`** — la destination mise à jour

**Réponse `400`** — erreur de validation ou zones invalides

---

### DELETE /api/smart-routings/geo/lists/{list}/destinations/{id}

Supprime une destination. Ses zones redeviennent disponibles.

**Réponse `200`**

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

---

## Lookup

### GET /api/smart-routings/geo/destinations/lookup

Trouve les destinations à utiliser pour un appelant. Généralement appelé depuis un flux d'appel 3CX. Accepte le scope `client` ou `cfd` et nécessite la permission `geo-routing-list.lookup`.

Le client doit correspondre au compte client sélectionné pour la requête.

**Paramètres de requête**

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `customer_account` | string | oui* | Compte client |
| `customer_id` | integer | oui* | Identifiant du client |
| `list_id` | integer | oui** | Le `list_id` numérique de la liste |
| `list_name` | string | oui** | Le nom de la liste |
| `number` | string | oui*** | Numéro de l'appelant. La zone en est déduite à l'aide du modèle géographique de la liste |
| `zone` | string | oui*** | Zone à rechercher directement (ex. `75`) |

*L'un des paramètres `customer_account` ou `customer_id` est obligatoire.  
**L'un des paramètres `list_id` ou `list_name` est obligatoire.  
***L'un des paramètres `number` ou `zone` est obligatoire. Si les deux sont envoyés, la zone déduite de `number` est prioritaire lorsque le numéro peut être analysé.

Si une destination de la liste couvre la zone, ses destinations sont renvoyées avec `fallback: false`. Sinon, ce sont les destinations de repli de la liste qui sont renvoyées, avec `fallback: true`.

**Réponse `200`**

```json
{
  "destination1": "201",
  "destination2": "202",
  "destination3": null,
  "destination4": null,
  "fallback": false
}
```

**Réponse `400`** — paramètres manquants

**Réponse `404`** — aucun client ou aucune liste correspondante, ou aucune destination (ni destination de repli) configurée