Creating Calls
Start or schedule an outbound call with one POST to /v1/calls, or from a no-code tool through an inbound webhook.
Showing instructions for Xebit VoiceCloud.Showing instructions for Xebit VoiceKit, on your own infrastructure. Switch with the selector at the top. Updated 22 October 2026.
You start a call with a single POST /v1/calls request, or, if your tool cannot hold an API key, with a POST to your inbound webhook URL. Either way you get back a call_id to track or cancel the call.
Before you begin
Three things must be in place or the call will not be placed.
1. Create an outbound agent
The agent is the AI voice that holds the conversation. Create at least one under the Xebit VoiceCloud dashboard → Agents → Create Agentthe Xebit VoiceKit admin console → Agents → Create Agent and choose Outbound as its type.
2. Give the agent a number from your own trunk
An outbound agent needs a number to call from. Xebit does not sell or assign numbers: the number is one on your own carrier or SIP trunk. Connect the trunk to Xebit, add the number, then attach it under the Xebit VoiceCloud dashboard → Agents → your agent → Phone Numbersthe Xebit VoiceKit admin console → Agents → your agent → Phone Numbers.
3. Generate an API key
Create a key with the calls:create scope under the Xebit VoiceCloud dashboard → Integrations → API Keysthe Xebit VoiceKit admin console → Integrations → API Keys. It is shown once, so store it safely.
Using a no-code tool instead of writing code? You only need steps 1 and 2. Use the inbound webhook method further down this page.
Create a call with the REST API
/v1/callsBest when you are building your own application. Authenticate with your API key.
curl -s -X POST "https://api.voice.xebit.ai/v1/calls" \
-H "x-api-key: $XEBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_123",
"user_number": "+91XXXXXXXXXX",
"user_name": "John Doe",
"user_email": "john.doe@example.com",
"scheduled_time": "2026-07-15T18:30:00Z",
"additional_info": {
"purpose": "Appointment Confirmation"
}
}'import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
response = requests.post(
f"{BASE_URL}/calls",
headers={"x-api-key": API_KEY},
json={
"agent_id": "agent_123",
"user_number": "+91XXXXXXXXXX",
"user_name": "John Doe",
"user_email": "john.doe@example.com",
"scheduled_time": "2026-07-15T18:30:00Z",
"additional_info": {
"purpose": "Appointment Confirmation"
}
}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const response = await fetch(`${BASE_URL}/calls`, {
method: "POST",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
agent_id: "agent_123",
user_number: "+91XXXXXXXXXX",
user_name: "John Doe",
user_email: "john.doe@example.com",
scheduled_time: "2026-07-15T18:30:00Z",
additional_info: {
purpose: "Appointment Confirmation"
}
})
});
console.log(response.status, await response.json());curl -s -X POST "https://<your-xebit-voicekit-host>/v1/calls" \
-H "x-api-key: $XEBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_123",
"user_number": "+91XXXXXXXXXX",
"user_name": "John Doe",
"user_email": "john.doe@example.com",
"scheduled_time": "2026-07-15T18:30:00Z",
"additional_info": {
"purpose": "Appointment Confirmation"
}
}'import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
response = requests.post(
f"{BASE_URL}/calls",
headers={"x-api-key": API_KEY},
json={
"agent_id": "agent_123",
"user_number": "+91XXXXXXXXXX",
"user_name": "John Doe",
"user_email": "john.doe@example.com",
"scheduled_time": "2026-07-15T18:30:00Z",
"additional_info": {
"purpose": "Appointment Confirmation"
}
}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const response = await fetch(`${BASE_URL}/calls`, {
method: "POST",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
agent_id: "agent_123",
user_number: "+91XXXXXXXXXX",
user_name: "John Doe",
user_email: "john.doe@example.com",
scheduled_time: "2026-07-15T18:30:00Z",
additional_info: {
purpose: "Appointment Confirmation"
}
})
});
console.log(response.status, await response.json());Sample response:
{
"data": {
"call_id": "call_abc123",
"scheduled_at": "2024-01-27T03:02:00.000Z",
"status": "queued"
}
}Request fields
| Name | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | ID of the AI agent that will make the call. |
user_number | string | Yes | Number to call, with country code, for example +91XXXXXXXXXX. |
user_name | string | No | The person's name. |
user_email | string | No | The person's email address. |
user_preferred_language | string | No | Language for this call only, for example "hindi". Falls back to the agent's configured language when omitted. |
additional_info | object | No | Variables your agent can reference during the call. Up to 25 key-value pairs. |
scheduled_time | string | No | ISO 8601 time to place the call. Must carry an explicit UTC offset and be in the future. Without it the call goes out about 15 seconds after the request. |
The Idempotency-Key request header is supported, so a retried request does not create a second call.
The legacy names contact_number, contact_name, contact_email and contact_preferred_language still work as aliases for the user_* fields. Do not send both forms of the same field in one request.
Scheduling a call for later
Set scheduled_time to queue the call for a particular moment, for example a reminder an hour before an appointment, instead of dialling right away.
scheduled_time must end in Z or an explicit offset such as +05:30: 2026-07-15T18:30:00Z or 2026-07-15T18:30:00+05:30. A bare value such as 2026-07-15T18:30:00 is rejected with 400, because it would otherwise be read in the server's local time zone and could map to a different real time depending on which server handled it.
Create a call with an inbound webhook
/v1/hooks/{YOUR_SECRET_TOKEN}Suited to automation tools, CRMs and anything else that can send a POST. The secret token in the URL authenticates the request, so no API key header is sent.
curl -s -X POST "https://api.voice.xebit.ai/v1/hooks/YOUR_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "call.create",
"data": {
"agent_id": "agent_123",
"contact_number": "+1234567890",
"contact_name": "Charlie"
}
}'import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
token = "YOUR_SECRET_TOKEN"
response = requests.post(
f"{BASE_URL}/hooks/{token}",
json={
"action": "call.create",
"data": {
"agent_id": "agent_123",
"contact_number": "+1234567890",
"contact_name": "Charlie"
}
}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const token = "YOUR_SECRET_TOKEN";
const response = await fetch(`${BASE_URL}/hooks/${token}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
action: "call.create",
data: {
agent_id: "agent_123",
contact_number: "+1234567890",
contact_name: "Charlie"
}
})
});
console.log(response.status, await response.json());curl -s -X POST "https://<your-xebit-voicekit-host>/v1/hooks/YOUR_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "call.create",
"data": {
"agent_id": "agent_123",
"contact_number": "+1234567890",
"contact_name": "Charlie"
}
}'import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
token = "YOUR_SECRET_TOKEN"
response = requests.post(
f"{BASE_URL}/hooks/{token}",
json={
"action": "call.create",
"data": {
"agent_id": "agent_123",
"contact_number": "+1234567890",
"contact_name": "Charlie"
}
}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const token = "YOUR_SECRET_TOKEN";
const response = await fetch(`${BASE_URL}/hooks/${token}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
action: "call.create",
data: {
agent_id: "agent_123",
contact_number: "+1234567890",
contact_name: "Charlie"
}
})
});
console.log(response.status, await response.json());The full list of inbound actions and fields is on Inbound Webhooks.
What happens next
Xebit queues the call, then connects your agent to the person over your trunk. Follow progress and the outcome through Call Status or, better at volume, Outbound Webhooks.
Keep the call_id from the response. You need it to read status or cancel the call.
Using additional_info in your agent prompt
Any key you send in additional_info can be dropped into the agent's prompt with double curly braces, so each conversation is personalised.
Request:
{
"agent_id": "agent_123",
"user_number": "+91XXXXXXXXXX",
"user_name": "John Doe",
"user_email": "john.doe@example.com",
"additional_info": {
"purpose": "Appointment Confirmation"
}
}Agent prompt:
Hi, this call is regarding: {{purpose}}. Please confirm if you will be attending.What the agent says: "Hi, this call is regarding: Appointment Confirmation. Please confirm if you will be attending."
additional_info takes up to 25 key-value pairs. Descriptive key names keep prompts easy to read.