Transfer a call
Moves the caller on a live phone call to a person. Send exactly one of destination_id (one of the transfer destinations set on the call’s agent) or to (any number in E.164, such as +971501234567; emergency numbers are refused). Any key can use destination_id; to needs a personal key (kbp_live_…), and a workspace key gets 403 personal_key_required. It is a cold transfer: the destination is dialled with the call’s own number and joins the caller when it answers; if it doesn’t, the agent carries on. Returns 202 with the attempt’s state and attempt_id; the outcome arrives as the call.transfer.completed or call.transfer.failed webhook, which names who asked (initiated_by, with user_id or service_account_id). Asking again while an attempt is in progress returns that attempt. Phone calls only, and only when live call control is switched on for your workspace’s calls: otherwise, or when the call isn’t connected, it returns 409 (transfer_unavailable, call_not_connected). The call’s capabilities.can_transfer says whether it can be transferred right now.
Scopes: call:read, call:control
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"
Path Parameters
Body
Response
Successful Response
Always true here; a refused transfer is a 409.
requested: the destination is being dialled; the outcome arrives as a webhook.
requested, completed The destination used (number for a typed number).
The transfer attempt's id.