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.

HTTP
x-api-key: xebit_live_your_api_key_here
Content-Type: application/json

Generate 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)

ScopeAllows
calls:createSchedule new calls with POST /v1/calls
calls:readRead call status and details with GET /v1/calls/:id
calls:cancelCancel pending calls with POST /v1/calls/:id/cancel
calls:deletePermanently delete a call and erase customer PII with DELETE /v1/calls/:id
appointments:readRead appointments, configuration, services and availability
appointments:writeCreate and update appointments
slots:readRead slot availability and schedule tracking records
slots:writeCreate, update and disable calendar windows; update and regenerate tracking

Call endpoints

Schedule a call

POST/v1/calls

Needs calls:create. Schedules a call with one of your agents. Send an Idempotency-Key header to make retries safe.

NameTypeRequiredDescription
agent_idstringYesThe agent that will hold the conversation.
user_numberstringYesNumber to call, E.164, +91 or +1.
user_namestringNoThe person's name.
user_emailstringNoThe person's email address.
user_preferred_languagestringNoLanguage for this call only, for example hindi. Overrides the agent default.
additional_infoobjectNoCustom 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"
    }
  }'
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"
    }
  }'

Response, 201 Created:

JSON
{
  "data": {
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "scheduled"
  }
}

Retrieve call status

GET/v1/calls/:call_id

Needs 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"
curl -s "https://<your-xebit-voicekit-host>/v1/calls/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: $XEBIT_API_KEY"

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.

JSON
{
  "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
  }
}
JSON
{
  "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

POST/v1/calls/:call_id/cancel

Needs 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"
curl -s -X POST "https://<your-xebit-voicekit-host>/v1/calls/550e8400-e29b-41d4-a716-446655440000/cancel" \
  -H "x-api-key: $XEBIT_API_KEY"
JSON
{
  "data": {
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled",
    "cancelled_at": "2024-01-27T03:01:00.000Z"
  }
}

Delete a call

DELETE/v1/calls/:call_id

Needs 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"
curl -s -X DELETE "https://<your-xebit-voicekit-host>/v1/calls/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: $XEBIT_API_KEY"
JSON
{
  "data": {
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "deleted": true
  }
}

Error codes

CodeMeaning
400Bad request: a field in the body is missing or invalid
401Unauthorised: the API key is missing or invalid
403Forbidden: the key lacks the scope this endpoint needs
409Conflict: the call cannot be cancelled because it has started or completed
422Unprocessable entity: the phone number format or country code is not supported
429Rate 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"
fi
#!/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"
fi