Using the API

Versioning and changelog

What we promise not to change, and what has changed.

The v1 promise#

The version is in the path — /api/v1 — and in every webhook payload — "apiVersion": "v1". While v1 is served, code written against it keeps working.

We will never, in v1:

• remove or rename an endpoint, a field, a header or an event type;
• change a field's type, or what one of its values means;
• make an optional field of a request required, or a request rule stricter;
• change an error code, or the HTTP status it comes with;
• take a scope away from an endpoint that a key holding it could call.

We may, at any time and without notice:

• add endpoints, optional request fields, response fields, headers and event types;
• add values to a list your code only reads, such as a new desk state, after announcing them here;
• reword an error's message — branch on code;
• change the order of fields in JSON, and the length of ids, cursors and secrets within their stated limits;
• loosen a limit, or tighten one that protects the service, such as a rate limit, with notice here.

So: ignore fields and event types you do not know, treat ids and cursors as opaque strings, and let an unknown status fall through to a sensible default rather than an exception.

The promise is held by the build, not only by us: every v1 endpoint, its scope, every field of its answer and every event are pinned by a test, and a change that breaks one fails before it can ship.

Deprecation#

A change that would break the promise ships as a new version, /api/v2, never as a change to v1. We announce changes in the changelog below, in advance where we can; there is no fixed notice period.

A single field or endpoint we mean to retire is marked deprecated in the reference first, and keeps working until the version it belongs to ends.

Changelog#

Every change to what the public API answers or sends, newest first.

October 2026 — v1 published #

• API keys with four scopes, and line and desk limits, made in Settings → Integrations.
• Seventeen endpoints: the business; lines, services and desks; visits — list, read, add, change, move along, mark urgent.
• Idempotency-Key on POST /v1/visits.
• Signed webhooks for seven event types, with retries, a delivery log, Send test event and Redeliver.
• Calls from a browser on any site are allowed (CORS, without credentials).