Changelog
Dated changes to the public API, with what to update in your integration.
Each entry lists breaking changes first, then additions. From now on, v1 only receives additive changes (Versioning).
2026-11-16
Breaking changes
GET /api/v1/agency/clientsnow requires the agency add-on on the calling workspace. Without it the call returns403permission_denied. See Agencies.- The workspace CRM webhook is retired.
getWorkspaceWebhookandsetWorkspaceWebhook(GETandPUT /api/v1/merchant/crm-webhook) are removed, and Settings → Developers → CRM webhook is gone from the console. Webhook endpoints are now the only workspace-wide webhook. - Each saved workspace CRM URL was moved to a webhook endpoint with the description "Migrated from CRM webhook", subscribed to
call.completedandcall.escalated, plus theticket.*events if ticket sync was on. The endpoint has a new signing secret: it does not reuse your old CRM secret. To see or replace it, rotate the secret in Settings → Developers → Webhooks, then update your receiver. - Those deliveries now use the endpoint envelope (
id,type,apiVersion,createdAt,data) and are signed with Standard Webhooks headers.X-Signature-SHA256is still sent, but it is keyed with the newwhsec_…secret. - Ticket events (
ticket.*) now go only to webhook endpoints. They are no longer sent to a ticket's campaign or agent webhook URL, to a user's saved URL or to the workspace URL, and theticketWebhookSyncEnabledsetting is removed. Subscribe an endpoint toticket.*to keep receiving them. - A call without a campaign or agent webhook URL is no longer sent to a URL saved by the user who created the call or the lead. See Campaign and agent webhooks.
2026-11-15
This release was the last one before general availability, and it includes breaking changes. Read Breaking changes before you upgrade an existing integration.
Breaking changes
API keys and authentication
- API keys get
403on every/auth/*route, includingGET /auth/me. To find out which workspace a key belongs to, callGET /api/v1/workspace. - API keys only work on the endpoints listed in the API reference, under
/api/v1. Any other route, including console-only routes and the/platform/v1alias, refuses keys with403api_key_route_forbidden. See Authentication. - A key acts with its creator's current role, so a manager who is made a lead now has keys that act as a lead. If the creator is deleted, suspended or blocked, or moves to another workspace, the key falls back to the workspace's primary manager. Each fallback is written to the audit log (Keys belong to the workspace).
Status codes and error codes
Errors now carry a dedicated error.code, and some status codes changed:
| Situation | Before | Now |
|---|---|---|
| Number is on the do-not-call list | 400 | 409 number_on_dnc |
Campaign is not running (callNow, callLeadNow, createCall, resume) | 400 | 409 campaign_not_running |
| Calling minutes used up | 400 | 402 payment_required |
| Campaign's daily call cap reached | 429 rate_limit_exceeded | 429 campaign_daily_cap_reached |
Other calling refusals now have their own codes: concurrent_call_limit_reached (429), carrier_capacity_reached (409), campaign_call_limit_reached (409), campaign_dial_busy (409), campaign_no_eligible_leads (409), campaign_leads_need_confirmation (409), campaign_not_ready (422), lead_has_no_campaign (422), dial_rejected (400) and dial_failed (502). Errors for a missing resource now name it, for example campaign_not_found or lead_not_found, where they used to return resource_not_found. All error codes lists every code.
Response shapes
callNowandcallLeadNownow wrap the new call in acallobject. Readcall.idandcall.status.createLeadandupdateLeadnormalise phone numbers to E.164 and refuse numbers they cannot parse with422invalid_phone_number(Phone numbers).- The do-not-call list returns at most 500 entries per request, with
hasMore(Pagination).
Validation
-
Agent
configvalues are validated. A known key with a bad value returns422parameter_invalidwithparamset to the config path. Unknown keys are dropped, not refused (Agents). -
POST /callsrefuses unknown body fields with422. -
Agent
configis limited to 512 KB (413payload_too_large) and 16 levels of nesting. This applies to create, update and import. -
Agent saves now refuse, with
422parameter_invalid:- tool URLs and
post_call_webhook.urlthat are not publichttp(s)addresses; - a
tools[].config.tool_idthat is not a tool in your workspace; - a
config.sttprovider that is not available.
Import drops such values with a warning instead (Import agents).
- tool URLs and
-
During a call, an inline
api_requesttool only accepts a relative path under its savedbase_url(Inline tools). -
The
agent_not_publishedcode was removed. Go-live publishes a pending draft first and refuses withagent_state_blocked.
Calls and idempotency
POST /callsdials once. It does not redial a call that was not answered, was busy or timed out, and a refused dial is not queued. A callback the agent books during the call is still placed (One request, one dial).- Responses that contain a one-time secret (webhook endpoint create and secret rotation) are never stored. Replaying the same
Idempotency-Keyreturns409idempotency_key_reused, not the secret again. - A request body over 1 MB skips idempotency and runs normally (Idempotency).
Webhooks
lead.createdis sent only for leads added one at a time:createLead, the console form and lead sources. Spreadsheet imports, campaign uploads and leads made automatically do not send it.- Test events and redeliveries are limited to 10 per endpoint per minute (
429rate_limit_exceeded).
- The public WhatsApp endpoints now live under
/api/v1/whatsapp, and their request and response fields are camelCase. Update the base path and field names if you used the earlier WhatsApp API (WhatsApp).
Added
- Error envelope: every error returns
detailplus anerrorobject withtype,code,message,param,docUrlandrequestId(Errors). - Webhooks v2: signed webhook endpoints per workspace, an event catalogue, test events, a delivery log, redelivery and secret rotation (Webhooks).
- Direct calls:
POST /callsplaces one call without building a campaign. It only dials your workspace's home country and has a daily limit per workspace (destination_not_allowed,daily_call_limit_reached). Also new: call transcript, recording, performance and daily counts (Place and read calls). - Agents: create, update a draft, publish, start, pause, test calls, voices and tools, plus agent import from Vapi, Retell and Bland (Agents).
- Workspace and usage:
GET /workspaceandGET /usagework with every key (Workspace and usage). - Tickets: list, create, update, notes, customer replies, categories and teams (Tickets).
- WhatsApp: send messages, read a message and list templates (WhatsApp).
- Leads: a lead fields catalogue and a callbacks list (Leads).
- Cursor pagination:
listLeadsandlistCallsaccept acursor. Page responses gainnextCursor,hasMoreandtotalCapped(Pagination). - Idempotency: create endpoints accept an
Idempotency-Keyheader (Idempotency). - Rate-limit headers: each key has its own limit, reported in
RateLimit-*headers (Rate limits). - API key limit: a workspace can hold 20 unexpired keys by default (
api_key_limit_reached). - Agency client list:
GET /api/v1/agency/clientslists an agency's client workspaces. Any agency key can call it if the key acts as a manager (Agencies). - Disabled-endpoint alert: when a webhook endpoint is disabled automatically, the workspace gets one alert: in the console, plus email or WhatsApp if those alerts are on (Automatic disabling).
- Developer hub in the console: Settings → Developers manages API keys, webhook endpoints (including test events, the delivery log and redelivery) and the CRM webhook.
- Stopping a campaign that is already stopped now succeeds.