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.

<code>Authorization: Bearer qcx_live_…</code>

API access requires an active Premium plan or above.

StatusWhen
401No key, a malformed key, or a key that is unknown or revoked.
403The key lacks the scope (This key cannot read.), or the plan has no API access.
400Bad paging parameters or body. The message says what is wrong.
413More than 1,000 contacts in one request.

Errors are { "error": "…" }.

Endpoints

Method and pathScopeFilters
GET /contactsreadnone
POST /contactswritenone
GET /conversationsreadchannel, status
GET /ticketsreadstatus

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.

ParameterMeaning
limit1 to 500, default 100.
updated_sinceOnly rows changed after this time, for example 2026-09-01T00:00:00Z.
cursorThe 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.

<code>curl -s "https://app.quantcx.com/api/v1/tickets?status=open&limit=200&updated_since=2026-11-01T00:00:00Z" \ -H "Authorization: Bearer $QUANTCX_API_KEY"</code>

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.

<code>curl -s -X POST https://app.quantcx.com/api/v1/contacts \ -H "Authorization: Bearer $QUANTCX_API_KEY" -H "Content-Type: application/json" \ -d '{ "client": "Acme", "contacts": [ { "email": "jane@example.com", "name": "Jane Doe", "source": "shop", "externalId": "user-42", "attributes": { "plan": "Business" } } ] }'</code>
FieldRules
emailRequired unless the row has a known source and externalId. Lower-cased, at most 254 characters.
name, role, phone, countryOptional; cut to 120, 80, 40 and 80 characters.
source, externalIdOptional identity in another system (80 and 200 characters).
clientThe client to file the contact under, by name or id. Per row, or once at the top level as the default.
attributesValues 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=.

<code>{ "id": "…", "channel": "widget", "status": "open", "handledBy": "ai", "subject": "Order delayed", "contact": { "name": "Jane Doe", "email": "jane@example.com" }, "client": "Acme", "agent": "…", "unread": 0, "outcome": null, "rating": null, "slack": null, "startedAt": "…", "createdAt": "…", "updatedAt": "…" }</code>

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=.

<code>{ "id": "…", "number": 48, "status": "open", "priority": "high", "subject": "Refund", "channel": "email", "requester": { "name": "Jane Doe", "email": "jane@example.com", "country": "DE" }, "client": "Acme", "assignee": null, "team": null, "tags": ["billing"], "category": null, "agent": "…", "conversationId": null, "firstResponseAt": null, "resolvedAt": null, "createdAt": "…", "updatedAt": "…" }</code>