Transfer a Call

POST

api

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}/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <x-auth-id>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "legs": "<string>",
  "aleg_url": "<string>",
  "aleg_method": "<string>",
  "bleg_url": "<string>",
  "bleg_method": "<string>"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/"

payload = {
    "legs": "<string>",
    "aleg_url": "<string>",
    "aleg_method": "<string>",
    "bleg_url": "<string>",
    "bleg_method": "<string>"
}
headers = {
    "X-Auth-ID": "<x-auth-id>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<x-auth-id>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    legs: '<string>',
    aleg_url: '<string>',
    aleg_method: '<string>',
    bleg_url: '<string>',
    bleg_method: '<string>'
  })
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

In PSTN transfer XML, set <Dial callerId> to a Vobiz number owned or authorized by your account. If you omit it, Vobiz derives the caller ID from the existing A-leg, which may not be authorized for the new outbound B-leg.

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

Field	Type	Required	Description
`auth_id`	string	Yes	Your Vobiz account ID (e.g., `{auth_id}`).
`call_uuid`	string	Yes	Unique identifier of the call to transfer.

string

required

Your Vobiz account ID, for example MA_XXXXXXXX.

string

required

Your Vobiz account ID. Use the same value in X-Auth-ID.

string

required

Unique identifier of the call to transfer.

Request Parameters

Field	Type	Required	Description
`legs`	string	No	Which leg(s) of the call to transfer. Values: `aleg` (caller), `bleg` (callee), or `both`. Default: `aleg`.
`aleg_url`	string	No	URL to transfer the A leg (caller) to. Must return valid XML with call instructions.
`aleg_method`	string	No	HTTP method for `aleg_url`. Values: `GET`, `POST`. Default: `POST`.
`bleg_url`	string	No	URL to transfer the B leg (callee) to. Must return valid XML with call instructions.
`bleg_method`	string	No	HTTP method for `bleg_url`. Values: `GET`, `POST`. Default: `POST`.

string

default:"aleg"

Which leg(s) of the call to transfer. One of aleg (caller), bleg (callee), or both.

string

URL to transfer the A leg (caller) to. Must return valid XML with call instructions.

string

default:"POST"

HTTP method for aleg_url. One of GET or POST.

string

URL to transfer the B leg (callee) to. Must return valid XML with call instructions.

string

default:"POST"

HTTP method for bleg_url. One of GET or 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

Field	Description
`api_id`	Unique identifier for this API request
`message`	Confirmation message indicating the transfer status
`call_uuid`	UUID of the call that was transferred

Error responses

Status	Meaning	How to handle
`400 Bad Request`	No 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 Unauthorized`	Missing/incorrect auth headers, or a lowercase path.	Use both auth headers and the PascalCase path.
`404 Not Found`	The `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"
}

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

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 callerId="+14155551234">
    <Number>+14156667890</Number>
  </Dial>
</Response>

Transfer a Call

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <x-auth-id>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "legs": "<string>",
  "aleg_url": "<string>",
  "aleg_method": "<string>",
  "bleg_url": "<string>",
  "bleg_method": "<string>"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/"

payload = {
    "legs": "<string>",
    "aleg_url": "<string>",
    "aleg_method": "<string>",
    "bleg_url": "<string>",
    "bleg_method": "<string>"
}
headers = {
    "X-Auth-ID": "<x-auth-id>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<x-auth-id>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    legs: '<string>',
    aleg_url: '<string>',
    aleg_method: '<string>',
    bleg_url: '<string>',
    bleg_method: '<string>'
  })
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

​Path parameters

​Request Parameters

​Response

​Response Fields

​Error responses

​Example Request

​Use Cases

Path parameters

Request Parameters

Response

Response Fields

Error responses

Example Request

Use Cases