Voice / Operations API

Higher-level, multi-step operations on a live call, such as transferring it to a new destination.

Transfer a call

POST/api/v1/voice/calls/{call_id}/transfer

Transfer an in-progress call to a new destination — a phone number (pstn) or a SIP URI (sip). Only cold transfers are currently supported. A call can have only one transfer in flight at a time.

The transfer is accepted asynchronously; a 202 means it has been started, not that the target has answered.

Auth: x-api-key header

Parameters

Name	In	Type	Description
`call_id` required	path	string

Request body

targetrequiredobject

Where to transfer the call.

kindrequired"pstn" | "sip" | "leg"

Destination type. pstn requires number; sip requires uri. leg is not yet supported.

numberstring | null

Destination phone number in E.164 format. Required when kind is pstn.

uristring | null

Destination SIP URI. Required when kind is sip.

leg_idstring | null

Existing leg to transfer to. Reserved for future use.

custom_headersobject | null

Custom SIP headers to attach to the outbound leg (sip targets only).

mode"cold" | "warm" | "monitor"

Transfer mode. Only cold is currently supported.

timeoutinteger

Seconds to wait for the target to answer before failing (1–600).

recordboolean | "mono" | "stereo" | "per_leg" | null

Override recording for the transferred call. Boolean, or a channel layout.

ringback"suppress" | "passthrough" | null

Whether the caller hears ringback while the target is dialed.

dial_musicobject | null

Audio to play to the caller while the target is being dialed.

actionrequired"play" | "say" | "hangup"

media_urlstring | null

textstring | null

voicestring | null

languagestring | null

reasonstring | null

loopboolean | null

confirm_soundobject | null

Audio the target hears before the call is bridged.

actionrequired"play" | "say" | "hangup"

media_urlstring | null

textstring | null

voicestring | null

languagestring | null

reasonstring | null

loopboolean | null

on_failureobject | null

Action to run on the caller if the transfer fails.

actionrequired"play" | "say" | "hangup"

media_urlstring | null

textstring | null

voicestring | null

languagestring | null

reasonstring | null

loopboolean | null

Example request

{
  "mode": "cold",
  "target": {
    "kind": "pstn",
    "number": "+14155559876"
  },
  "timeout": 30
}

Responses

Status	Description
`202`	The transfer was accepted and is being placed.
`400`	The transfer target or mode is invalid (e.g. missing `number` for a `pstn` target, or an unsupported mode).
`403`	The `x-api-key` header is missing or invalid.
`404`	No call matches the supplied identifier for this account.
`409`	A transfer is already in progress for this call.
`422`	The request body or query parameters failed validation.
`503`	The call-control service is temporarily unavailable. Safe to retry.

Example response (202)

{
  "call_id": "cs_01JQ8Z9K7M3N2P4R5S6T7V8W9X",
  "id": "op_01JQ8Z9K7M3N2P4R5S6T7V8WOP",
  "mode": "cold",
  "request_id": "req_9f8e7d6c5b4a3f2e1d0c9b8a",
  "status": "initiated"
}