Smart Routings

Smart Routings decide where an incoming call goes, based on inbound rules (call queues), opening hours, exceptions, geography, CTI keys or contacts. For a functional overview, see the Smart Routings documentation.

This page covers the concepts shared by every Smart Routings endpoint, then the inbound rule endpoints. The other resources have their own pages:

Headers: Authorization: Bearer {workspace-token}

#Selecting the customer account

Smart Routings data belongs to a customer account. Every Smart Routings endpoint (and the other customer-scoped endpoints such as integration keys or call history) needs to know which customer it acts on. The customer is not deduced from the token: pass it in the request.

The parameter is usually sent in the query string (?customer_account=ACME01); it is also read from the body.

The request is rejected with 403 when:

• no customer matches the parameters (No valid account specified.);
• the authenticated user does not belong to that customer (You do not have access to this account.);
• the OAuth client is restricted to another customer (This credential is not authorized for this account.).

Use GET /api/customers/resolve to check which customer a credential and a customer_account resolve to.

#Scopes and authentication

Call flows usually authenticate with a CFD token, exchanged for a short cfd-scoped access token. Any OAuth token with the client scope also works on the lookups (see Authentication).

#Permissions

Permissions are checked against the authenticated user's role. The workspace owner and users with the superadmin role have every permission.

#Conventions

• Write endpoints expect a JSON body (Content-Type: application/json), except the import endpoint (multipart).
• Lists are paginated (see Pagination) and accept filter[...], sort and include parameters as documented per endpoint. Text filters match partial values.
• Validation errors return 400 with a hint array:

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

• Business rule errors return a message:

{ "message": "The provided time span conflicts with another span for this entity." }

• Destination types, used by inbound rules, time spans and exceptions: extension, voicemail, call_queue, end_call, external_number, other.
• Local time. Time spans and exceptions are evaluated in the customer's timezone (the timezone setting, see PUT /api/customers/settings).

#Inbound rules (call queues)

An inbound rule describes a 3CX queue or a DID number, its default destination, and optionally the group it inherits time spans and exceptions from.

#The inbound rule object

{
  "id": 5,
  "customer_id": 12,
  "call_queue_group_id": 2,
  "active": true,
  "name": "Support",
  "host_name": "acme.3cx.eu",
  "type": "queue",
  "code": "SUP",
  "number": "800",
  "did_number": null,
  "default_destination_type": "voicemail",
  "default_destination": "800",
  "created_at": "2025-01-15T09:30:00.000000Z",
  "updated_at": "2025-01-20T16:02:11.000000Z",
  "group": { "id": 2, "name": "Business hours" }
}

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

Returns the inbound rules of the customer, most recently updated first.

Query parameters

Response 200 — paginated list of inbound rule objects

#GET /api/smart-routings/call-queues/queues/{id}

Returns an inbound rule with its group, exceptions and time_spans.

Response 200 — inbound rule object

#POST /api/smart-routings/call-queues/queues

Creates an inbound rule for the customer. When call_queue_group_id is set, the group's time spans and exceptions are copied to the new rule.

Request body

Response 201 — the created inbound rule object

#PUT /api/smart-routings/call-queues/queues/{id}

Updates an inbound rule. Accepts the same fields as the creation, all optional.

Moving the rule to another group replaces its time spans and exceptions with copies of the new group's. Setting call_queue_group_id to null detaches it: the copies become the rule's own, editable rows.

Response 201 — the updated inbound rule object

#DELETE /api/smart-routings/call-queues/queues/{id}

Deletes an inbound rule with its time spans and exceptions.

Response 200

{ "response": "element deleted" }

#PATCH /api/smart-routings/call-queues/queues/bulk

Updates several inbound rules of the customer at once. Only the fields present in the body are changed. Requires call-queue.edit.

Request body

{ "ids": [5, 6, 9], "default_destination_type": "voicemail", "default_destination": "800" }

Response 200 — array of the updated inbound rule objects

#DELETE /api/smart-routings/call-queues/queues/bulk

Deletes several inbound rules of the customer, along with their time spans and exceptions. Requires call-queue.delete. Rules of another customer are ignored.

Request body

Response 200

{ "response": "elements deleted" }

#Groups

A group shares its time spans and exceptions with every inbound rule it contains. The rules receive locked copies: only their destination and destination_type can be changed on the rule itself.

#The group object

{
  "id": 2,
  "customer_id": 12,
  "name": "Business hours",
  "created_at": "2025-01-10T08:00:00.000000Z",
  "updated_at": "2025-01-10T08:00:00.000000Z",
  "queues_count": 4
}

queues_count is only present in lists.

#GET /api/smart-routings/call-queues/groups

Returns the groups of the customer, most recently updated first.

Query parameters

Response 200 — paginated list of group objects

#GET /api/smart-routings/call-queues/groups/{id}

Returns a group with its queues, exceptions and time_spans.

Response 200 — group object

#POST /api/smart-routings/call-queues/groups

Request body

Response 201 — the created group object

#PUT /api/smart-routings/call-queues/groups/{id}

Request body

Response 201 — the updated group object

#DELETE /api/smart-routings/call-queues/groups/{id}

Deletes a group. Its inbound rules are kept and detached from the group; the copies they had inherited become their own rows.

Response 200

{ "response": "element deleted" }

#Time spans

A time span routes calls to a destination during an opening period, either every week (day_of_week) or on a specific date (date_full). A time span belongs to an inbound rule or to a group: every time span endpoint that lists or creates spans identifies that parent with two query parameters.

An inbound rule that belongs to a group cannot have its own time spans: create them on the group (422).

#The time span object

{
  "id": 31,
  "source_time_span_id": null,
  "imported_at": null,
  "time_spanable_id": 5,
  "time_spanable_type": "call_queue",
  "reference": "morning",
  "destination": "800",
  "destination_type": "call_queue",
  "day_of_week": 1,
  "date_full": null,
  "start_time": "08:30:00",
  "end_time": "12:30:00",
  "created_at": "2025-01-15T09:35:00.000000Z",
  "updated_at": "2025-01-15T09:35:00.000000Z"
}

#GET /api/smart-routings/call-queues/time-spans

Query parameters

Response 200 — paginated list of time span objects

#GET /api/smart-routings/call-queues/time-spans/{id}

Returns a time span with its parent (time_spanable).

Response 200 — time span object

#POST /api/smart-routings/call-queues/time-spans

Creates a time span on the parent given in the query string. Time spans created on a group are copied to every inbound rule of the group.

Request body

*Provide day_of_week or date_full. If both are sent, day_of_week is ignored.

Response 201 — the created time span object

Response 422 — the span overlaps another span of the same parent on the same day

#PUT /api/smart-routings/call-queues/time-spans/{id}

Updates a time span. Accepts the same fields, all optional. On a locked span (inherited from a group), only destination and destination_type can be sent (422 otherwise).

Response 201 — the updated time span object

#DELETE /api/smart-routings/call-queues/time-spans/{id}

Deletes a time span. Locked spans cannot be deleted (403): delete them on the group.

Response 200

{ "response": "element deleted" }

#POST /api/smart-routings/call-queues/time-spans/bulk

Creates the same opening period on several days at once: one span per value of day_of_week and of date_full. Requires the time_spanable_type and time_spanable_id query parameters.

Request body

*Provide day_of_week, date_full, or both.

{
  "day_of_week": [1, 2, 3, 4, 5],
  "start_time": "08:30:00",
  "end_time": "12:30:00",
  "destination_type": "call_queue",
  "destination": "800"
}

Response 201 — array of all the time spans of the parent

Response 422 — one of the spans conflicts with an existing span

#PATCH /api/smart-routings/call-queues/time-spans/bulk

Changes the destination of several time spans of the parent. Works on locked spans.

Request body

Response 200 — array of the updated time span objects

#DELETE /api/smart-routings/call-queues/time-spans/bulk

Deletes several time spans of the parent.

Request body

Without ids, every time span of the parent is deleted.

Response 200

{ "response": "elements deleted" }

Response 403 — one of the targeted spans is locked (inherited from a group)

#Exceptions

An exception overrides the time spans on a given day (public holiday, closure…). Exceptions take priority over time spans. Like time spans, they belong to an inbound rule or a group, identified with two query parameters on the list, create and bulk endpoints.

An inbound rule that belongs to a group cannot have its own exceptions: create them on the group (422).

#The exception object

{
  "id": 77,
  "source_exception_id": null,
  "exceptionable_id": 2,
  "exceptionable_type": "call_queue_group",
  "reference": "France:christmasDay",
  "label": "Christmas",
  "destination": "800",
  "destination_type": "voicemail",
  "day": "2026-12-25",
  "created_at": "2026-01-05T10:00:00.000000Z",
  "updated_at": "2026-01-05T10:00:00.000000Z"
}

source_exception_id is set on locked copies inherited from a group.

#GET /api/smart-routings/call-queues/exceptions

Query parameters

Response 200 — paginated list of exception objects

#GET /api/smart-routings/call-queues/exceptions/{id}

Returns an exception with its parent (exceptionable).

Response 200 — exception object

#POST /api/smart-routings/call-queues/exceptions

Request body

Response 201 — the created exception object

Response 400 — the reference already exists, or another exception exists on that day

#PUT /api/smart-routings/call-queues/exceptions/{id}

Updates an exception. Accepts the same fields, all optional. On a locked exception, only destination and destination_type can be sent (422 otherwise).

Response 201 — the updated exception object

#DELETE /api/smart-routings/call-queues/exceptions/{id}

Deletes an exception. Locked exceptions cannot be deleted (403).

Response 200

{ "response": "element deleted" }

#PATCH /api/smart-routings/call-queues/exceptions/bulk

Changes the destination of several exceptions of the parent. Works on locked exceptions.

Request body

Response 200 — array of the updated exception objects

#DELETE /api/smart-routings/call-queues/exceptions/bulk

Deletes several exceptions of the parent.

Request body

Response 200

{ "response": "elements deleted" }

Response 403 — one of the targeted exceptions is locked

#GET /api/smart-routings/call-queues/exceptions/holidays

Lists the countries available for public holiday import.

Response 200

{ "countries": ["Andorra", "Argentina", "Australia", "Austria", "Belgium", "...", "France", "..."] }

#POST /api/smart-routings/call-queues/exceptions/holidays

Creates one exception per public holiday of a country on the parent given by exceptionable_type and exceptionable_id. Without year, the holidays falling within the next 12 months (starting today, possibly spanning two calendar years) are created; with year, those of that calendar year. Each exception gets the holiday name as label and {country}:{holiday} as reference (e.g. France:christmasDay).

A holiday is skipped when the parent already has an exception on that day, so the request can be repeated without creating duplicates.

Request body

Response 201 — array of the created exception objects (empty when every holiday already had an exception)

Response 422 — unknown country or invalid year

#Import and export

The inbound rules of a customer can be exported to and imported from a spreadsheet. The file has one row per time span; inbound rules without time spans have a single row.

#GET /api/smart-routings/call-queues/export

Downloads the customer's inbound rules as inbound_rules.xlsx. Requires call-queue.view.

Response 200 — Excel file

#POST /api/smart-routings/call-queues/import

Imports inbound rules from an .xlsx or .csv file (CSV: ; delimiter, " enclosure). Requires call-queue.create. Send the request as multipart/form-data.

Rules are matched on type and number (or DID number): existing rules are updated, others are created. The whole file is validated first and imported in a single transaction: if one row is invalid, nothing is imported.

Form fields

Response 200

{ "response": "Import successful." }

Response 422 — invalid rows

{
  "response": "The import failed validation.",
  "failures": [
    {
      "row": 4,
      "attribute": "host_name",
      "errors": ["The selected host_name is invalid."],
      "values": { "name": "Support", "number": "800", "type": "queue", "host_name": "unknown.3cx.eu" }
    }
  ]
}

#Inbound rule lookup

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

Returns the destination of an inbound rule at a given moment. This is the endpoint a call flow calls when a call comes in. Accepts the client or cfd scope and requires call-queue.lookup.

The destination is chosen in this order:

1. an exception on that day;
2. a time span on that specific date (date_full) covering the time;
3. a weekly time span (day_of_week) covering the time.

Only active rules are considered. Day and time are evaluated in the customer's timezone.

Query parameters

*Provide customer_account or customer_id. **Provide one of queue_id, queue_number or queue_name (checked in that order).

Response 200

{
  "reference": "morning",
  "destination": "800",
  "label": null,
  "inherited": true,
  "matched": "time_span,day_of_week"
}

Response 404

{ "message": "No destination found matching given parameters." }

Other 404 messages: No customer found matching given parameters., No queue found matching given parameters.. When nothing matches, apply the rule's default destination in your call flow.

Response 400 — invalid parameters, or invalid day/time

#CFD tokens

A CFD token is a long-lived secret designed for call flows (3CX Call Flow Designer). It is attached to a user and exchanged for a short access token with the cfd scope, which only gives access to the lookup endpoints and to survey recording.

CFD tokens are workspace-level: they are not filtered by customer, but the endpoints still require customer_account.

#The CFD token object

{
  "id": 3,
  "user_id": 8,
  "name": "Main call flow",
  "token": "q8V3...80 characters...Xz",
  "hosts": ["203.0.113.10"],
  "expires_at": "2027-01-01T00:00:00.000000Z",
  "created_at": "2026-01-05T10:00:00.000000Z",
  "updated_at": "2026-01-05T10:00:00.000000Z",
  "expired": false,
  "user": { "id": 8, "name": "Call flow bot", "group": "admin", "email": "cfd@acme.com" }
}

The token value is returned by every CFD token endpoint. Treat it as a password.

The list endpoint does not return hosts.

#GET /api/smart-routings/cfd-tokens

Requires cfd-token.view.

Query parameters

Response 200 — paginated list of CFD token objects

#GET /api/smart-routings/cfd-tokens/{id}

Requires cfd-token.view. Non-admin users can only read their own tokens.

Response 200 — CFD token object

#POST /api/smart-routings/cfd-tokens

Creates a CFD token. The token value is generated (80 characters). Requires cfd-token.create.

Request body

Response 201 — the created CFD token object

#PUT /api/smart-routings/cfd-tokens/{id}

Updates a CFD token (user_id, name, hosts, expires_at). The token value cannot be changed. Allowed to admin users and to the token's owner.

Response 201 — the updated CFD token object

#DELETE /api/smart-routings/cfd-tokens/{id}

Allowed to admin users and to the token's owner.

Response 200

{ "response": "element deleted" }

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

Exchanges a CFD token for an access token with the cfd scope. No Authorization header is needed.

Response 200

{
  "message": "success",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...",
  "expires_at": "2026-10-09T11:42:00+00:00",
  "user": { "id": 8, "name": "Call flow bot", "email": "cfd@acme.com", ... }
}

Use the returned token as the Bearer token of the lookup calls. It is valid for 1 hour (expires_at): exchange the CFD token again on each call rather than storing the access token.

Response 403

{ "message": "Host not authorised." }

Response 404 — unknown token, expired token, or its user no longer exists

{ "message": "This token does not exists or has expired." }

The expiry is checked on every exchange: once expires_at is past, the CFD token can no longer be exchanged for an access token. A token without expires_at never expires. The check in the controller:

if (! $cfdToken || $cfdToken->expired) {
    return response()->json([
        'message' => 'This token does not exists or has expired.',
    ], 404);
}

Expiring or deleting a CFD token also revokes the access tokens it issued: the lookups made with them answer 401 straight away.