Skip to main content
POST
/
api
/
v1
/
Account
/
{auth_id}
/
Call
/
{call_uuid}
/
Transfer a Call
curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/
POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/
Transfer an in-progress call to a different URL for new call flow instructions. The new URL must return XML instructions that define the next steps for the call. Use this to implement call forwarding, IVR navigation, or dynamic call routing.
Authentication required:
  • X-Auth-ID - Your account Auth ID
  • X-Auth-Token - Your account Auth Token
  • Content-Type: application/json
The call must be in an active state (in-progress) to be transferred. You can transfer both call legs independently using their respective UUIDs.
Transfer operations interrupt the current call flow and immediately execute the XML returned from the new URL. Ensure your transfer URL is accessible and returns valid XML.

​
Path parameters

FieldTypeRequiredDescription
auth_idstringYesYour Vobiz account ID (e.g., {auth_id}).
call_uuidstringYesUnique identifier of the call to transfer.

​
Request Parameters

FieldTypeRequiredDescription
legsstringNoWhich leg(s) of the call to transfer. Values: aleg (caller), bleg (callee), or both. Default: aleg.
aleg_urlstringNoURL to transfer the A leg (caller) to. Must return valid XML with call instructions.
aleg_methodstringNoHTTP method for aleg_url. Values: GET, POST. Default: POST.
bleg_urlstringNoURL to transfer the B leg (callee) to. Must return valid XML with call instructions.
bleg_methodstringNoHTTP method for bleg_url. Values: GET, POST. Default: POST.
Transfer Leg Options:
  • aleg - Transfers only the caller (A leg) to the new URL. Provide aleg_url.
  • bleg - Transfers only the callee (B leg) to the new URL. Provide bleg_url.
  • both - Transfers both legs to their respective URLs (requires both aleg_url and bleg_url).
Pass the call_uuid of the leg you are transferring in the path. The legs value tells Vobiz which side of that call to redirect. When transferring aleg, the B-leg keeps running its current flow (and vice versa) - use both to redirect the whole session at once.
Transfer is request-and-execute: as soon as the matching URL returns valid XML, the current flow is interrupted and the new XML runs immediately. If the URL is unreachable, times out, or returns invalid XML, the affected leg may be dropped. Host the transfer URL on reliable HTTPS infrastructure and return XML quickly.

​
Response

Returns a success message confirming the call transfer request has been initiated.
Response - 202 Accepted
{
  "api_id": "uuid-here",
  "message": "call transferred",
  "call_uuid": "call-uuid-here"
}

​
Response Fields

FieldDescription
api_idUnique identifier for this API request
messageConfirmation message indicating the transfer status
call_uuidUUID of the call that was transferred

​
Error responses

StatusMeaningHow to handle
400 Bad RequestNo transfer URL supplied for the selected legs (e.g. legs=both without both aleg_url and bleg_url), or a malformed URL.Send the URL(s) matching your legs value.
401 UnauthorizedMissing/incorrect auth headers, or a lowercase path.Use both auth headers and the PascalCase path.
404 Not FoundThe call_uuid is not an active call (already ended or never existed).The call must be in-progress to transfer. Confirm with Retrieve a Live Call.
This action only works on calls in the in-progress state. Queued or completed calls return 404.

​
Example Request

{
  "legs": "aleg",
  "aleg_url": "https://yourdomain.com/transfer_instructions/",
  "aleg_method": "POST"
}

​
Use Cases

  • Implement call forwarding based on IVR input
  • Route calls to different departments dynamically
  • Play announcements or collect additional information mid-call
  • Implement warm transfer scenarios with hold music
  • Change call behavior based on external triggers or events
XML Response Example: Your transfer URL should return XML instructions like:
<Response>
  <Speak>Please hold while we transfer your call.</Speak>
  <Dial callerId="+14155551234">
    <Number>+14156667890</Number>
  </Dial>
</Response>