IllyVoIPdevelopers

Voice API

Transfer call

Starts a tracked transfer and returns a transfer ID.

Try in API Playground ↗Sign in to prepare and run this request.
POST/api/v1/voice/call-control/transfer

Before you start

Choose the supported destination for an active call and provide the required request fields.

Result

Track the transfer result rather than treating acceptance as a completed transfer.

Charges and safe retries

This changes where the caller is connected. Review transfer conditions and charges first.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X POST "https://api.illyvoip.com/api/v1/voice/call-control/transfer" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}" \
  -H "Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call_control_id": "YOUR_CALL_CONTROL_ID",
    "target": {
        "type": "pstn",
        "value": "YOUR_DESTINATION_NUMBER"
    }
}'

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/voice/call-control/transfer", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY,
    "Idempotency-Key": "YOUR_UNIQUE_IDEMPOTENCY_KEY",
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "call_control_id": "YOUR_CALL_CONTROL_ID",
    "target": {
        "type": "pstn",
        "value": "YOUR_DESTINATION_NUMBER"
    }
})
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/voice/call-control/transfer');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY'),
        'Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => '{
    "call_control_id": "YOUR_CALL_CONTROL_ID",
    "target": {
        "type": "pstn",
        "value": "YOUR_DESTINATION_NUMBER"
    }
}',
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "POST",
    "https://api.illyvoip.com/api/v1/voice/call-control/transfer",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"],
        "Idempotency-Key": "YOUR_UNIQUE_IDEMPOTENCY_KEY",
        'Content-Type': 'application/json'
    },
    json=json.loads("{\n    \"call_control_id\": \"YOUR_CALL_CONTROL_ID\",\n    \"target\": {\n        \"type\": \"pstn\",\n        \"value\": \"YOUR_DESTINATION_NUMBER\"\n    }\n}"),
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request body

application/json

Body required.

call_control_idstringrequired

Live control session ID.

nullable false
targetobjectoptional

Tracked destination object with type and value. Supported types: pstn, sip_user.

View nested fields
typestringrequired
valuestringrequired

Additional properties: not allowed.

tostringoptional

Backward-compatible PSTN destination shortcut.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "call_control_id": {
      "type": "string",
      "nullable": false,
      "description": "Live control session ID."
    },
    "target": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "type": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "value"
      ],
      "description": "Tracked destination object with `type` and `value`. Supported types: `pstn`, `sip_user`."
    },
    "to": {
      "type": "string",
      "description": "Backward-compatible PSTN destination shortcut."
    }
  },
  "required": [
    "call_control_id"
  ]
}
Example body
JSON
{
  "call_control_id": "vapi_760da5ee5a3c8b70777bae20fbda",
  "target": {
    "type": "pstn",
    "value": "+33145512022"
  }
}

Request behavior

Use this after a gather result or business-logic decision. The transfer runs asynchronously and should be tracked through the transfer-status endpoint.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • call_control_id: Control session reference returned by Create or Answer; use it for subsequent live actions.
  • transfer_id: Public reference used to check or cancel this transfer.
  • transfer: Transfer state and result details.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

JSON
{
  "status": "success",
  "call_control_id": "vapi_760da5ee5a3c8b70777bae20fbda",
  "transfer_id": "xfer_a36f61b5370ff6d4b8396c1f2d1a89ee",
  "transfer": {
    "state": "connecting",
    "message": "Connecting transfer destination…",
    "target_type": "pstn",
    "target_value": "+33145512022",
    "can_cancel": true
  }
}
statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
transfer_idstringrequired
transferobjectrequired
View nested fields
statestringrequired
messagestringrequired
target_typestringrequired
target_valuestringrequired
can_cancelbooleanrequired

Additional properties: not allowed.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success"
      ]
    },
    "call_control_id": {
      "type": "string",
      "nullable": false
    },
    "transfer_id": {
      "type": "string"
    },
    "transfer": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "state": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "target_type": {
          "type": "string"
        },
        "target_value": {
          "type": "string"
        },
        "can_cancel": {
          "type": "boolean"
        }
      },
      "required": [
        "state",
        "message",
        "target_type",
        "target_value",
        "can_cancel"
      ]
    }
  },
  "required": [
    "status",
    "call_control_id",
    "transfer_id",
    "transfer"
  ]
}
400 The request failed validation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key or browser token is missing or invalid.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
402 The account has insufficient available credit.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 The account is not allowed to perform this operation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
404 The requested owned resource was not found.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
409 The request conflicts with the current resource or operation state.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The request rate limit was exceeded.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected service error occurred.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 The service is temporarily unavailable.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable, failed

Try this operation in Sandbox · Environment setup and limitations

List active callsGet Voice API statusCreate callExecute action chainAnswer inbound Voice API callPlay audioSpeak textGather DTMF or speechGet call statusWaitGet transfer statusCancel transferHold callUnhold callSend DTMFEnd call

Search API operations, parameters, SDK and webhooks.