Navigation
CX-Engine API · 2 min read

Introduction

Overview of the CX-Engine REST API — architecture, base URLs, authentication and error handling.

#Overview

The CX-Engine API is a REST API that returns JSON responses. It is split into two distinct layers that reflect the platform's multi-tenant architecture:

  • Central API — account-level operations (registration, login, workspace management, invitations)
  • Workspace API — tenant-level operations (customers, contacts, users, integration keys, etc.)

#Available resources

Page Endpoints
Authentication OAuth 2.0, login, logout, token switching
Customers Customer accounts, account resolution, regional settings
CRM Lookup Contact search and creation, call and chat logging in the connected CRM
Call History Calls received by CX-Engine
Users, Roles & Invitations Users, roles, organisations, invitations
Contacts Contacts of the customer accounts
Integration Keys CRM integration keys of a customer
Smart Routings Inbound rules, groups, time spans, exceptions, lookups, CFD tokens
Smart Routings — CTIs, Contacts, Geo Routing, Surveys Other Smart Routings resources

#Customer-scoped endpoints

Many workspace endpoints act on a single customer account (CRM lookups, call history, integration keys, Smart Routings). The customer is not deduced from the token: pass it with the customer_account query parameter. See Selecting the customer account.

#Base URLs

Layer Base URL
Central API https://{central-domain}/api
Workspace API https://{workspace-subdomain}.{central-domain}/api

The workspace subdomain is assigned when a workspace is created (e.g. mycompany.cx-engine.app).

#Authentication

All authenticated endpoints require a Bearer token sent in the Authorization header:

Authorization: Bearer {token}

Tokens are obtained via the /api/login endpoint (see Authentication). Tokens are issued per scope: a central token works only against the central API; a workspace token works only against that workspace's API.

To switch between a central token and a workspace token, use the POST /api/switch-to endpoint.

#Request Format

Authenticated write endpoints (POST, PUT) expect a JSON body:

Content-Type: application/json

#Response Format

All responses are JSON objects. Successful responses generally include the requested data directly. Error responses follow this shape:

{
  "message": "Human-readable error description.",
  "error": "machine_readable_code"
}

Validation errors include a hint array with field-level messages:

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

#HTTP Status Codes

Code Meaning
200 OK — request succeeded
201 Created — resource was created or updated
400 Bad Request — malformed request or validation failure
401 Unauthorized — missing or invalid token
403 Forbidden — authenticated but not permitted
404 Not Found — resource does not exist
422 Unprocessable — semantic validation error
500 Internal Server Error

#Pagination

List endpoints that support pagination return a standard paginated response:

{
  "data": [...],
  "current_page": 1,
  "last_page": 4,
  "per_page": 20,
  "total": 72
}

Pass ?per_page=N to control page size and ?page=N to navigate pages.