API Keys
Base URL, the x-api-key header, key scopes, the four call endpoints and their error codes.
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.
An API key lets an outside system create, read, cancel and delete calls, and work with appointments. Each key carries one or more scopes, so give an integration only the access it actually uses.
Destination numbers must be in E.164 format. Indian (+91XXXXXXXXXX) and US (+1XXXXXXXXXX) numbers are supported today.
How many keys you can have
On Xebit VoiceCloud, a Base plan organisation can hold up to 5 active keys. Professional and Enterprise plans have no cap. Revoked keys do not count.
On Xebit VoiceKit, the number of active keys is governed by your own deployment's configuration. Revoked keys do not count.
Base URL
https://api.voice.xebit.ai/v1
https://<your-xebit-voicekit-host>/v1
Authentication
Put the key in the x-api-key header of every request and send JSON bodies with Content-Type: application/json.
x-api-key: xebit_live_your_api_key_here
Content-Type: application/jsonGenerate keys in the Xebit VoiceCloud dashboard under Integrations → API Keys.
Generate keys in the Xebit VoiceKit admin console of your deployment under Integrations → API Keys.
Keep the key in an environment variable. Never hard code it or commit it to version control.
Permissions (scopes)
| Scope | Allows |
|---|---|
calls:create | Schedule new calls with POST /v1/calls |
calls:read | Read call status and details with GET /v1/calls/:id |
calls:cancel | Cancel pending calls with POST /v1/calls/:id/cancel |
calls:delete | Permanently delete a call and erase customer PII with DELETE /v1/calls/:id |
appointments:read | Read appointments, configuration, services and availability |
appointments:write | Create and update appointments |
slots:read | Read slot availability and schedule tracking records |
slots:write | Create, update and disable calendar windows; update and regenerate tracking |
Call endpoints
Schedule a call
/v1/callsNeeds calls:create. Schedules a call with one of your agents. Send an Idempotency-Key header to make retries safe.
| Name | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | The agent that will hold the conversation. |
user_number | string | Yes | Number to call, E.164, +91 or +1. |
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. Overrides the agent default. |
additional_info | object | No | Custom key-value pairs your agent can use. |
The older names contact_number, contact_name, contact_email and contact_preferred_language are still accepted as aliases for the user_* fields. Use the user_* names in new work. Sending both names for the same field returns 400 VALIDATION_ERROR.
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": "+919876543210",
"user_name": "Raj Patel",
"user_email": "raj@company.com",
"user_preferred_language": "hindi",
"additional_info": {
"company": "Acme Corp",
"deal_stage": "negotiation"
}
}'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": "+919876543210",
"user_name": "Raj Patel",
"user_email": "raj@company.com",
"user_preferred_language": "hindi",
"additional_info": {
"company": "Acme Corp",
"deal_stage": "negotiation"
}
}
)
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: "+919876543210",
user_name: "Raj Patel",
user_email: "raj@company.com",
user_preferred_language: "hindi",
additional_info: {
company: "Acme Corp",
deal_stage: "negotiation"
}
})
});
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": "+919876543210",
"user_name": "Raj Patel",
"user_email": "raj@company.com",
"user_preferred_language": "hindi",
"additional_info": {
"company": "Acme Corp",
"deal_stage": "negotiation"
}
}'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": "+919876543210",
"user_name": "Raj Patel",
"user_email": "raj@company.com",
"user_preferred_language": "hindi",
"additional_info": {
"company": "Acme Corp",
"deal_stage": "negotiation"
}
}
)
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: "+919876543210",
user_name: "Raj Patel",
user_email: "raj@company.com",
user_preferred_language: "hindi",
additional_info: {
company: "Acme Corp",
deal_stage: "negotiation"
}
})
});
console.log(response.status, await response.json());Response, 201 Created:
{
"data": {
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "scheduled"
}
}Retrieve call status
/v1/calls/:call_idNeeds calls:read. Returns the current state and details of one call.
curl -s "https://api.voice.xebit.ai/v1/calls/550e8400-e29b-41d4-a716-446655440000" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.get(
f"{BASE_URL}/calls/{call_id}",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(`${BASE_URL}/calls/${callId}`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s "https://<your-xebit-voicekit-host>/v1/calls/550e8400-e29b-41d4-a716-446655440000" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.get(
f"{BASE_URL}/calls/{call_id}",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(`${BASE_URL}/calls/${callId}`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());Response, 200 OK. status is one of scheduled, in_progress, completed, failed or cancelled. call_direction is outbound or inbound; for inbound calls call_from is set and call_to is null.
{
"data": {
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "scheduled",
"call_direction": "outbound",
"call_to": "+919876543210",
"call_from": null,
"call_duration_seconds": null,
"agent_id": "agent_123",
"agent_name": "Sales Agent",
"call_recording": "https://voice.xebit.ai/calls/550e8400-e29b-41d4-a716-446655440000",
"call_analytics": null,
"call_transcript": null,
"call_triggered_at": null,
"scheduled_at": "2024-01-27T03:02:00.000Z",
"completed_at": null,
"error": null
}
}{
"data": {
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "scheduled",
"call_direction": "outbound",
"call_to": "+919876543210",
"call_from": null,
"call_duration_seconds": null,
"agent_id": "agent_123",
"agent_name": "Sales Agent",
"call_recording": "https://<your-xebit-voicekit-host>/calls/550e8400-e29b-41d4-a716-446655440000",
"call_analytics": null,
"call_transcript": null,
"call_triggered_at": null,
"scheduled_at": "2024-01-27T03:02:00.000Z",
"completed_at": null,
"error": null
}
}Cancel a call
/v1/calls/:call_id/cancelNeeds calls:cancel. Works on calls in pending or scheduled status. Returns 409 if the call has already started or finished.
curl -s -X POST "https://api.voice.xebit.ai/v1/calls/550e8400-e29b-41d4-a716-446655440000/cancel" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.post(
f"{BASE_URL}/calls/{call_id}/cancel",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(`${BASE_URL}/calls/${callId}/cancel`, {
method: "POST",
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s -X POST "https://<your-xebit-voicekit-host>/v1/calls/550e8400-e29b-41d4-a716-446655440000/cancel" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.post(
f"{BASE_URL}/calls/{call_id}/cancel",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(`${BASE_URL}/calls/${callId}/cancel`, {
method: "POST",
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());{
"data": {
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "cancelled",
"cancelled_at": "2024-01-27T03:01:00.000Z"
}
}Delete a call
/v1/calls/:call_idNeeds calls:delete. Permanently deletes a completed call and erases the end customer's PII (transcript, contact details, recording metadata). Only calls with a recorded engagement can be deleted; anything else returns 404. See Deleting Calls.
curl -s -X DELETE "https://api.voice.xebit.ai/v1/calls/550e8400-e29b-41d4-a716-446655440000" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.delete(
f"{BASE_URL}/calls/{call_id}",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(`${BASE_URL}/calls/${callId}`, {
method: "DELETE",
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s -X DELETE "https://<your-xebit-voicekit-host>/v1/calls/550e8400-e29b-41d4-a716-446655440000" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.delete(
f"{BASE_URL}/calls/{call_id}",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(`${BASE_URL}/calls/${callId}`, {
method: "DELETE",
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());{
"data": {
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"deleted": true
}
}Error codes
| Code | Meaning |
|---|---|
400 | Bad request: a field in the body is missing or invalid |
401 | Unauthorised: the API key is missing or invalid |
403 | Forbidden: the key lacks the scope this endpoint needs |
409 | Conflict: the call cannot be cancelled because it has started or completed |
422 | Unprocessable entity: the phone number format or country code is not supported |
429 | Rate limit exceeded: back off and retry after the delay given |
Full example
One script that creates a call, reads its status and then tries to cancel it.
#!/bin/bash
API_KEY="$XEBIT_API_KEY"
BASE_URL="https://api.voice.xebit.ai/v1"
# Create a call
CALL_ID=$(curl -s -X POST "$BASE_URL/calls" \
-H "x-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_123",
"user_number": "+919876543210",
"user_name": "Raj Patel",
"user_email": "raj@company.com",
"additional_info": {"company": "Acme Corp", "deal_stage": "negotiation"}
}' | jq -r '.data.call_id')
echo "Created: $CALL_ID"
# Read its status
STATUS=$(curl -s "$BASE_URL/calls/$CALL_ID" -H "x-api-key: $API_KEY" | jq -r '.data.status')
echo "Status: $STATUS"
# Cancel it
CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "$BASE_URL/calls/$CALL_ID/cancel" \
-H "x-api-key: $API_KEY")
if [ "$CODE" = "409" ]; then
echo "Too late to cancel: the call has started or finished"
else
echo "Cancelled"
fiimport os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
session = requests.Session()
session.headers.update({
"x-api-key": os.environ["XEBIT_API_KEY"],
"Content-Type": "application/json",
})
# Create a call
res = session.post(f"{BASE_URL}/calls", json={
"agent_id": "agent_123",
"user_number": "+919876543210",
"user_name": "Raj Patel",
"user_email": "raj@company.com",
"additional_info": {"company": "Acme Corp", "deal_stage": "negotiation"},
})
res.raise_for_status()
call_id = res.json()["data"]["call_id"]
print("Created:", call_id)
# Read its status
res = session.get(f"{BASE_URL}/calls/{call_id}")
res.raise_for_status()
print("Status:", res.json()["data"]["status"])
# Cancel it
res = session.post(f"{BASE_URL}/calls/{call_id}/cancel")
if res.status_code == 409:
print("Too late to cancel: the call has started or finished")
else:
res.raise_for_status()
print("Cancelled:", res.json()["data"]["status"])const BASE_URL = "https://api.voice.xebit.ai/v1";
const headers = {
"x-api-key": process.env.XEBIT_API_KEY,
"Content-Type": "application/json",
};
// Create a call
const createRes = await fetch(`${BASE_URL}/calls`, {
method: "POST",
headers,
body: JSON.stringify({
agent_id: "agent_123",
user_number: "+919876543210",
user_name: "Raj Patel",
user_email: "raj@company.com",
additional_info: { company: "Acme Corp", deal_stage: "negotiation" },
}),
});
if (!createRes.ok) throw new Error(`Create failed: ${createRes.status}`);
const { data: { call_id } } = await createRes.json();
console.log("Created:", call_id);
// Read its status
const statusRes = await fetch(`${BASE_URL}/calls/${call_id}`, { headers });
const { data: call } = await statusRes.json();
console.log("Status:", call.status);
// Cancel it
const cancelRes = await fetch(`${BASE_URL}/calls/${call_id}/cancel`, { method: "POST", headers });
if (cancelRes.status === 409) {
console.log("Too late to cancel: the call has started or finished");
} else if (!cancelRes.ok) {
throw new Error(`Cancel failed: ${cancelRes.status}`);
} else {
const { data } = await cancelRes.json();
console.log("Cancelled:", data.status);
}#!/bin/bash
API_KEY="$XEBIT_API_KEY"
BASE_URL="https://<your-xebit-voicekit-host>/v1"
# Create a call
CALL_ID=$(curl -s -X POST "$BASE_URL/calls" \
-H "x-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_123",
"user_number": "+919876543210",
"user_name": "Raj Patel",
"user_email": "raj@company.com",
"additional_info": {"company": "Acme Corp", "deal_stage": "negotiation"}
}' | jq -r '.data.call_id')
echo "Created: $CALL_ID"
# Read its status
STATUS=$(curl -s "$BASE_URL/calls/$CALL_ID" -H "x-api-key: $API_KEY" | jq -r '.data.status')
echo "Status: $STATUS"
# Cancel it
CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "$BASE_URL/calls/$CALL_ID/cancel" \
-H "x-api-key: $API_KEY")
if [ "$CODE" = "409" ]; then
echo "Too late to cancel: the call has started or finished"
else
echo "Cancelled"
fiimport os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
session = requests.Session()
session.headers.update({
"x-api-key": os.environ["XEBIT_API_KEY"],
"Content-Type": "application/json",
})
# Create a call
res = session.post(f"{BASE_URL}/calls", json={
"agent_id": "agent_123",
"user_number": "+919876543210",
"user_name": "Raj Patel",
"user_email": "raj@company.com",
"additional_info": {"company": "Acme Corp", "deal_stage": "negotiation"},
})
res.raise_for_status()
call_id = res.json()["data"]["call_id"]
print("Created:", call_id)
# Read its status
res = session.get(f"{BASE_URL}/calls/{call_id}")
res.raise_for_status()
print("Status:", res.json()["data"]["status"])
# Cancel it
res = session.post(f"{BASE_URL}/calls/{call_id}/cancel")
if res.status_code == 409:
print("Too late to cancel: the call has started or finished")
else:
res.raise_for_status()
print("Cancelled:", res.json()["data"]["status"])const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const headers = {
"x-api-key": process.env.XEBIT_API_KEY,
"Content-Type": "application/json",
};
// Create a call
const createRes = await fetch(`${BASE_URL}/calls`, {
method: "POST",
headers,
body: JSON.stringify({
agent_id: "agent_123",
user_number: "+919876543210",
user_name: "Raj Patel",
user_email: "raj@company.com",
additional_info: { company: "Acme Corp", deal_stage: "negotiation" },
}),
});
if (!createRes.ok) throw new Error(`Create failed: ${createRes.status}`);
const { data: { call_id } } = await createRes.json();
console.log("Created:", call_id);
// Read its status
const statusRes = await fetch(`${BASE_URL}/calls/${call_id}`, { headers });
const { data: call } = await statusRes.json();
console.log("Status:", call.status);
// Cancel it
const cancelRes = await fetch(`${BASE_URL}/calls/${call_id}/cancel`, { method: "POST", headers });
if (cancelRes.status === 409) {
console.log("Too late to cancel: the call has started or finished");
} else if (!cancelRes.ok) {
throw new Error(`Cancel failed: ${cancelRes.status}`);
} else {
const { data } = await cancelRes.json();
console.log("Cancelled:", data.status);
}