Place a call
Queues an outbound call from a published agent to to (E.164), optionally from one of your numbers. Returns 202: the call is queued, so poll GET /v1/calls/{call_id} or listen for the call.ended webhook. Send an Idempotency-Key. Emergency numbers and numbers on your do-not-call list are refused; test_mode calls the agent’s draft.
Scopes: call:create
Authorizations
An API key from Settings → API keys, sent as Authorization: Bearer kb_live_…. A workspace key starts kb_; a personal key starts kbp_ and acts as its owner.
Headers
A unique key (a UUID works) for this request. Retrying with the same key returns the first answer instead of running twice.
255The API version to answer as, a date (YYYY-MM-DD). Leave it out for the current version (2026-11-07). An unknown version is refused with 400 unsupported_api_version.
2026-11-07 "2026-11-07"
Body
The agent that makes the call. It must be published and allowed to dial out.
The number to call, in E.164 (e.g. +971501234567).
8 - 20The caller ID, in E.164: one of your numbers. Omit to use the agent's caller number.
8 - 20Values for the agent's {{variables}} (e.g. first_name). At most 50 keys.
Your own data, stored with the call and sent back in its webhooks. At most 50 keys.
Your own reference for the call (e.g. a CRM id).
120A test call: it may use the agent's unpublished draft, and it is labelled as a test in lists and reports.
Response
Successful Response
The call's id (call_…).
phone, or web for a browser call.
phone, web Whether the agent answered it or made it.
inbound, outbound Where the call is now. completed, failed and canceled are final.
requested, queued, dialing, ringing, connected, ending, completed, failed, canceled How it ended; null while it is live.
answered, busy, no_answer, rejected, abandoned, provider_failed, runtime_failed, canceled, unknown A stop you asked for that the carrier hasn't confirmed yet.
none, cancel_requested, hangup_requested The review flag: needs_review until someone marks it reviewed.
none, needs_review, reviewed Bumped on every change. Send it back as If-Match on a write.
The agent on the call.
The agent version the call ran.
The external party, masked.
The external party's country (ISO 3166-1 alpha-2).
The person who placed it, if one did.
The team it belongs to, if any.
When it was requested (ISO 8601).
When it was answered (ISO 8601).
When it ended (ISO 8601).
How long it rang.
How long the conversation lasted.
Ringing plus talking.
Dial attempts made.
Why it ended, in a stable code.
An error code when it failed.
Whether the minutes used are final yet.
Whether the cost is final yet (complete once settled).
Whether every call event arrived.
A recording can be downloaded.
A transcript can be read.
The caller was moved to a person or number.
Where it was transferred to, masked.
How it was transferred.
When it was transferred (ISO 8601).
What this key may do to this call.
Whether the post-call analysis has run.
pending, running, complete, skipped, failed When the analysis ran (ISO 8601).
What the call achieved, e.g. booked or callback.
The caller's mood, from -1 (negative) to 1 (positive).
positive, neutral or negative.
A short summary. Null without call:content.
The caller's name, if they gave it. Null without call:content.
The caller's company. Null without call:content.
The caller's email. Null without call:content.
When the caller asked to be called back (ISO 8601).
Labels on the call.
Why it was flagged for review.
When it was marked reviewed (ISO 8601).
When it was archived (ISO 8601).
The call's cost in millionths of currency, once settled.
The cost's currency (ISO 4217), once settled.