REST API
Read contacts, conversations and tickets with cursor pagination and incremental sync, and push up to 1,000 contacts per call, with a workspace API key.
Base URL: https://app.quantcx.com/api/v1. Requests and responses are JSON. Every call is scoped to the workspace the key belongs to: there is no way to name another workspace.
Authentication
Owners and admins create keys under Settings > Channels & API > API Keys, with the read scope, the write scope, or both. A key starts with qcx_live_ and is shown once; only its hash is stored, so a lost key is replaced, not recovered. Revoked keys stop working immediately.
API access requires an active Premium plan or above.
| Status | When |
|---|---|
| 401 | No key, a malformed key, or a key that is unknown or revoked. |
| 403 | The key lacks the scope (This key cannot read.), or the plan has no API access. |
| 400 | Bad paging parameters or body. The message says what is wrong. |
| 413 | More than 1,000 contacts in one request. |
Errors are { "error": "…" }.
Endpoints
| Method and path | Scope | Filters |
|---|---|---|
GET /contacts | read | none |
POST /contacts | write | none |
GET /conversations | read | channel, status |
GET /tickets | read | status |
Pagination and incremental sync
Every list is ordered by updatedAt, oldest change first (ties broken by id), and paged with a cursor rather than an offset, so rows that change while you page are neither skipped nor repeated.
| Parameter | Meaning |
|---|---|
limit | 1 to 500, default 100. |
updated_since | Only rows changed after this time, for example 2026-09-01T00:00:00Z. |
cursor | The nextCursor from the previous page. Treat it as opaque. |
Responses are { "data": [...], "nextCursor": "…" | null }. Follow nextCursor until it is null, remember the last updatedAt you saw, and pass it as updated_since on your next run.
GET /contacts
<code>{ "id": "…", "email": "jane@example.com", "name": "Jane Doe", "role": null, "phone": null, "country": "DE", "source": "shop", "externalId": "user-42", "client": "Acme", "verified": true, "verifiedVia": "email", "attributes": { "plan": "Business" }, "identities": [{ "source": "shop", "externalId": "user-42" }], "createdAt": "…", "updatedAt": "…" }</code>POST /contacts
Creates or updates up to 1,000 contacts per request. Matching is identity first, then email: a row with a source and externalId seen before updates that person even if the email changed; otherwise the email decides.
| Field | Rules |
|---|---|
email | Required unless the row has a known source and externalId. Lower-cased, at most 254 characters. |
name, role, phone, country | Optional; cut to 120, 80, 40 and 80 characters. |
source, externalId | Optional identity in another system (80 and 200 characters). |
client | The client to file the contact under, by name or id. Per row, or once at the top level as the default. |
attributes | Values for the workspace's own fields, keyed by the key shown in Contacts > Manage attributes. Unknown keys are dropped; values are cut to 500 characters. |
A bad row never fails the call; it is skipped and reported by index:
<code>{ "added": 1, "updated": 0, "identities": 1, "skipped": [{ "index": 3, "email": "", "reason": "Not an email address." }] }</code>GET /conversations
Chats and Slack threads, without their messages. Filter with ?channel= and ?status=.
GET /tickets
Tickets without their timeline. id is the stable UUID; number is the per-workspace number people read on the ticket. Filter with ?status=.