Connect Your Call Flow

#Overview

Your call flow talks to Smart Routings with plain HTTP GET requests and reads JSON responses. In 3CX, build it with the Call Flow Designer; any PBX whose call flow can send an HTTP request and read a JSON value works the same way.

All URLs below are relative to your workspace API:

https://your-workspace.cx-engine.com/api

Send Accept: application/json on every request, so that errors are also returned as JSON.

Every lookup needs your account, passed as customer_account (your CX-Engine account identifier) or customer_id.

#Authentication

The lookup endpoints require a Bearer token:

Authorization: Bearer {access-token}

The token belongs to a CX-Engine user. That user must have access to the account and, in their role, the Lookup permission on the resources the call flow queries (Inbound rules, Geographic, CTI).

#CFD token (recommended for call flows)

A CFD token is a long secret designed for call flows. The call flow exchanges it for an access token:

GET /api/smart-routings/cfd-auth/t/{cfd-token}

{
  "message": "success",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "expires_at": "2026-10-09T11:42:00+00:00",
  "user": { "id": 12, "name": "Call flows", "...": "..." }
}

Use the returned token as the Bearer token of the lookups. It carries the cfd scope, which only gives access to the lookup endpoints and to survey recording. It is valid for 1 hour: have the call flow exchange the CFD token on each call. Expiring or deleting the CFD token revokes its access tokens immediately.

A CFD token can be restricted to a list of IP addresses (hosts). A request from another address gets 403 Host not authorised.

A CFD token can also have an expiry date (expires_at). Once it is past, the exchange answers 404 This token does not exists or has expired. A token without expiry date never expires.

CFD tokens are created through the API. See CX-Engine API › Smart Routings.

#OAuth token

Any OAuth access token of a user with the client scope also works on the lookups. It is required to read routing contacts, which the cfd scope does not cover. See CX-Engine API › Authentication.

#Inbound rule lookup

Returns the destination of an inbound rule at the current date and time.

GET /api/smart-routings/call-queues/lookup

day and time are read in the timezone of your account. Use them to test a schedule ("what happens on 25 December at 10:00?").

Example

GET /api/smart-routings/call-queues/lookup?customer_account=ACME&queue_number=800

Response 200 — a time span matches

{
  "reference": "open",
  "destination": "801",
  "label": null,
  "inherited": false,
  "matched": "time_span,day_of_week"
}

Response 200 — an exception matches

{
  "reference": "France:christmasDay",
  "destination": "999",
  "label": "Christmas Day",
  "inherited": false,
  "matched": "exception"
}

See How the destination is chosen for the evaluation order.

Errors

queue_number only matches queue rules. For a DID rule, query by queue_name or queue_id.

#Geographic lookup

Returns the destinations of a geographic list for a caller.

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

Example

GET /api/smart-routings/geo/destinations/lookup?customer_account=ACME&list_id=1&number=0472000000

Response 200

{
  "destination1": "810",
  "destination2": "811",
  "destination3": null,
  "destination4": null,
  "fallback": false
}

fallback is true when the caller's zone is not covered by the list: the four values are then the list's fallback destinations. If all four values are empty, the API answers 404 No destination found matching given parameters. An unknown list returns 404 No list found matching given parameters.

#CTI lookup

#Token URL

Copy the Lookup URL from the CTI page and append the calling number. No other authentication is needed:

GET /api/smart-routings/ctis/t/{cti-token}/{origin}

{
  "id": 42,
  "origin": "0033612345678",
  "destination": "https://erp.example.com/customers/1234"
}

The origin must match exactly. If there is no match, the API answers 404.

#Authenticated lookup

With a Bearer token (cfd or client scope), call GET /api/smart-routings/ctis/lookup with:

Example

GET /api/smart-routings/ctis/lookup?customer_account=ACME&cti_name=VIP%20callers&origin=0033612345678

Response 200

{
  "id": 42,
  "cti_id": 4,
  "origin": "0033612345678",
  "destination": "https://erp.example.com/customers/1234",
  "created_at": "2024-03-04T10:15:00.000000Z",
  "updated_at": "2024-03-04T10:15:00.000000Z"
}

Without a match, the API answers 404 with No customer found matching given parameters., No CTI found matching given parameters. or No destination found matching given parameters.

#Surveys

Call flows can also record the answers of a post-call survey with POST /api/smart-routings/survey-records, using the same token. The answers are listed in Routings > Surveys. See CX-Engine API › Smart Routings for the payload.