Vobiz Logo
Vobiz
|API Documentation
Console
← Back to Call Management

Transfer a Call

Transfer an in-progress call to a different URL for new call flow instructions.

This endpoint allows you to redirect an active call to a new XML URL. The new URL should return XML instructions that define the next steps for the call. This is useful for implementing features like call forwarding, IVR navigation, or dynamic call routing.

Authentication Required:

  • • X-Auth-ID: Your account ID (e.g., {Auth_ID})
  • • X-Auth-Token: Your account Auth Token
  • • Content-Type: application/json

Note: The call must be in an active state (in-progress) to be transferred. You can transfer both call legs independently using their respective UUIDs.

Important: 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.

HTTP Request

POSTPOST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/

Path Parameters

auth_idstringRequired

Your Vobiz account ID (e.g., {Auth_ID})

call_uuidstringRequired

Unique identifier of the call to transfer

Request Parameters

Request Parameters

NameTypeDescription
legs
stringSpecifies which leg(s) of the call to transfer. Values: "aleg" (caller), "bleg" (callee), or "both". Default: "aleg".
aleg_url
stringURL to transfer the A leg (caller) to. Must return valid XML with call instructions.
aleg_method
stringHTTP method to request the aleg_url. Values: "GET" or "POST". Default: "POST".
bleg_url
stringURL to transfer the B leg (callee) to. Must return valid XML with call instructions.
bleg_method
stringHTTP method to request the bleg_url. Values: "GET" or "POST". Default: "POST".

Transfer Leg Options:

  • alegTransfers only the caller (A leg) to the new URL
  • blegTransfers only the callee (B leg) to the new URL
  • bothTransfers both legs to their respective URLs (requires both aleg_url and bleg_url)

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

api_id - Unique identifier for this API request
message - Confirmation message indicating the transfer status

Example Request

Transfer A Leg (Caller) Only

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

Transfer Both Legs

Request Body
{
  "legs": "both",
  "aleg_url": "https://example.com/transfer/aleg",
  "aleg_method": "POST",
  "bleg_url": "https://example.com/transfer/bleg",
  "bleg_method": "POST"
}

cURL Example

cURL Request
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/ \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legs": "both",
    "aleg_url": "https://example.com/transfer/aleg",
    "aleg_method": "POST",
    "bleg_url": "https://example.com/transfer/bleg",
    "bleg_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>
    <Number>+14156667890</Number>
  </Dial>
</Response>
Retrieve a Call
Hang Up a Call