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

POST/v1/calls

Best 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"
    }
  }'
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"
    }
  }'

Sample response:

JSON
{
  "data": {
    "call_id": "call_abc123",
    "scheduled_at": "2024-01-27T03:02:00.000Z",
    "status": "queued"
  }
}

Request fields

NameTypeRequiredDescription
agent_idstringYesID of the AI agent that will make the call.
user_numberstringYesNumber to call, with country code, for example +91XXXXXXXXXX.
user_namestringNoThe person's name.
user_emailstringNoThe person's email address.
user_preferred_languagestringNoLanguage for this call only, for example "hindi". Falls back to the agent's configured language when omitted.
additional_infoobjectNoVariables your agent can reference during the call. Up to 25 key-value pairs.
scheduled_timestringNoISO 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

POST/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"
    }
  }'
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"
    }
  }'

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:

JSON
{
  "agent_id": "agent_123",
  "user_number": "+91XXXXXXXXXX",
  "user_name": "John Doe",
  "user_email": "john.doe@example.com",
  "additional_info": {
    "purpose": "Appointment Confirmation"
  }
}

Agent prompt:

Text
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.