Transfer a live call
Bridge a live call to a human, ending the agent's part of the conversation.
Bridge a live call to a human, ending the agent's part of the conversation.
Use this when an agent needs to hand off mid-conversation. The customer stays
on the line and is connected to transfer_to; the AI drops out. The
caller ID presented on the outbound leg is resolved from the original call.
202, not 200. The transfer has been accepted by the telephony provider,
which then has to ring the destination — it may not answer. Confirm with
GET /v2/calls/{execution_id}.
409 covers the two states where a transfer is not possible: the call has already ended, or it has been placed but has not yet reported a leg to bridge (retry in a moment). 404 means no such call in your organisation.
Mid-call transfer is not supported on every carrier; a call placed through one that does not support it answers 400.
Rate limit: 600 requests per minute per organization (bucket calls.create). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/calls/{execution_id}/transferAuthorization
AuthorizationRequiredBearer <token>
Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.
In: header
Request Body
application/jsonRequiredtransfer_toRequiredTransfer To
Where to bridge the call: an E.164 phone number (+919812345678) or a SIP URI (sip:agent@voip.example.com).
timeoutTimeout | null
Ring timeout on the transfer leg, 5-120 seconds. Defaults to 30.
Path Parameters
execution_idRequiredExecution Id
The call's id, as returned by POST /v2/calls or GET /v2/calls.
Query Parameters
organization_idOrganization Id
Must match the organisation the API key belongs to.
Response Body
202
The transfer has been handed to the telephony provider.
execution_idRequiredExecution Id
The call that was transferred.
transfer_toRequiredTransfer To
The destination the call was bridged to.
statusStatus
Always 'transferred'. Confirm the final outcome with GET /v2/calls/{execution_id}.
"transferred"400
1000 — malformed or contradictory input (bad transfer target, bad timeout).
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
402
1400 — the organisation has insufficient credits for this request.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
403
1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
404
1200 — no such resource in this organisation. Cross-tenant reads answer 404, never 403.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
409
1201 — the call's state does not allow this action (already ended, or not yet dialled).
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — per-organisation rate limit exceeded. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
503
1501 — the telephony service is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
504
1502 — the telephony service did not respond in time.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
The transfer has been handed to the telephony provider.