---
title: Contacts and Geographic Routing
excerpt: Route known callers with routing contacts and custom fields, route by caller region with geographic lists, and map callers to URLs with CTI tables.
order: 4
---

Inbound rules answer *"is it open, and where do calls go right now?"*. The features below answer *"who is calling, and where should this caller go?"*. Your call flow can combine them: for example, look up the caller first, then fall back to the inbound rule.

## Routing contacts

A routing contact is a known caller: a customer, a key account, a partner. Go to **Routings** > **Contacts** and click **Add contact**.

| Field | Description |
|---|---|
| **Company**, **First name**, **Last name** | Company or last name is required. |
| **Unique identifier** | Optional numeric code. Lets the caller identify themselves by typing it when their number is not recognised. |
| **Language code** | Two letters, for example `fr` or `en`. Lets the call flow pick the language of its prompts. |
| **Numbers** | The caller's phone numbers. Press `,` or space to add each one. |
| **Telecom destination** | The queue or number this contact should be routed to when calling. |
| **Email destination** | Destination for incoming emails, for ticketing systems. |
| **Custom fields** | The active fields defined in **Routings** > **Fields**. |

> [!WARNING]
> Numbers are searched as text. Store them in the same format as the caller ID your PBX sends to the call flow (for example `0033612345678` or `+33612345678`), otherwise the contact is not found.

### Custom fields

Go to **Routings** > **Fields** to add your own fields to every contact: contract level, account manager, VIP flag, language…

| Field | Description |
|---|---|
| **Type** | **Destination** (a free value, typically an additional destination), **True or false**, or **Multiple choices**. |
| **Code** | Identifier returned to the call flow. Letters, numbers, `-` and `_` only. Cannot be changed once created. |
| **Label** | Name displayed in the interface. |
| **Active** | Inactive fields are hidden from the contact form. |
| **Options** | For **Multiple choices**: each option has a **value** (returned by the API) and a **label** (displayed in the interface). |

> [!WARNING]
> Call flows reference fields by their **code**. That is why the code is locked after creation: renaming it would silently break the call flows that use it.

### Querying contacts from a call flow

Contacts are read through the API: `GET /api/smart-routings/contacts` with the `filter[telecoms]` parameter (caller number) or `filter[id_code]` (code typed by the caller). Each contact is returned with a `fields` array (`code`, `label`, `type`, `value`). This endpoint requires a token with the `client` scope: see [Connect your call flow](/en/docs/smart-routings/connect-call-flow#authentication).

### Export and import

Select contacts in the list and click **Export** to download them. The file has one column per contact field (`id`, `id_code`, `language_code`, `company`, `first_name`, `last_name`, `emails`, `telecoms`, `email_destination`, `telecom_destination`), then one column per custom field, headed by the field's **code**:

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

- **True or false** fields hold `1` or `0`. The import also accepts `true`/`false`, `yes`/`no` and `oui`/`non`.
- **Multiple choices** fields hold the option **value**. The import also accepts the option label.

The same file can be imported back through the API, which updates the contacts that have an `id` and creates the others. Deleting contacts, one by one or in bulk, also deletes their custom field values. See [CX-Engine API › Smart Routings › Contacts](/en/docs/cx-api/smart-routings-contacts#bulk-operations).

## Geographic routing

Geographic routing sends a caller to a destination based on where they call from: the nearest agency, the right regional team.

Go to **Routings** > **Geographic** and create a list:

| Field | Description |
|---|---|
| **Name** | Name of the list. The call flow can query the list by this name (`list_name`). |
| **Unique identifier** | A number of your choice. The call flow can query the list by this number (`list_id`). |
| **Geographic model** | How a caller number is turned into a zone, for example French departments or countries (ISO 3166-1 alpha-2 codes). Models are provided by CX-Engine. |
| **Fallback destination 1 to 4** | Returned when the caller's zone is not covered by any destination of the list. |

Then, on the list page, click **Add destination** and set:

- a **Name**
- up to four destinations (**Destination 1** to **Destination 4**), for example a primary and backup queue
- the **zones** covered by this destination

Each zone can only belong to one destination of the list. The list page shows the **Available zones** of the model and the **Uncovered zones**, which fall back to the fallback destinations.

Numbers without an international prefix are read as French numbers.

## CTI tables

A CTI table maps an **origin** (the calling number) to a **destination**, usually a URL, for example the page of the customer in your business application.

1. Go to **Routings** > **CTI** and click **Add CTI**.
2. On the CTI page, add each origin and destination with **Add destination**.
3. Copy the **Lookup URL** shown on the CTI page.

The lookup URL contains a secret token and does not need any other authentication. Use **Regenerate token** if the URL leaks: the previous URL stops working.

See [Connect your call flow](/en/docs/smart-routings/connect-call-flow#cti-lookup) for the request format.