Skip to main content
The POST /calls/outbound endpoint lets you trigger an AI-powered outbound call from any external system. Use it to fire calls directly from your CRM when a lead is created, from an automation platform like Zapier or Make when a form is submitted, or from your own application when a specific event occurs. You can customize the agent’s greeting, inject customer-specific context, and pass dynamic variables — all without permanently changing the agent’s configuration.

​
Endpoint

POST https://api.voiceinfra.ai/v1/calls/outbound

​
Request headers

​
X-API-Key
string
required
Your VoiceInfra API key. Generate one from Settings → API Keys in your dashboard.
​
Content-Type
string
required
Must be application/json.

​
Request body

​
agent_id
string
required
The ID of the AI agent to use for this call. Find the agent ID in the API tab inside your agent’s settings in the VoiceInfra dashboard.
​
from_number
string
required
The caller ID displayed to the person you are calling. Must be in E.164 format (for example, +18005551234). The number must be configured in your VoiceInfra account under Phone Numbers.
​
to_number
string
required
The phone number to call. Must be in E.164 format (for example, +14155550100).
​
first_message
string
Override the agent’s default opening line for this specific call. Use this to personalise the greeting with the contact’s name or call-specific details without editing the agent permanently.
​
context
string
Additional context injected into the agent’s system prompt for this call only. Pass details such as the customer’s account tier, their last purchase, or any other information that should shape the agent’s behaviour during the conversation.
​
variables
object
Key-value pairs injected as dynamic variables in the agent’s prompts. For example, {"name": "Sarah", "company": "Acme"}. Reference variables in your agent’s prompt template using the variable names you define here.

​
Full example request

cURL
curl -X POST https://api.voiceinfra.ai/v1/calls/outbound \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "from_number": "+18005551234",
    "to_number": "+14155550100",
    "first_message": "Hi Sarah, this is calling to confirm your appointment tomorrow at 2pm.",
    "variables": {
      "name": "Sarah",
      "company": "Acme Corp",
      "appointment_time": "tomorrow at 2pm"
    }
  }'

​
Response

A successful request returns 200 OK with a JSON body confirming the call has been queued.
​
call_id
string
Unique identifier for the initiated call. Use this to match the webhook event sent when the call completes.
​
status
string
Always queued on a successful response — the call has been accepted and will connect shortly.
​
agent_id
string
The agent ID used for this call, echoed from your request.
​
to_number
string
The destination phone number, echoed from your request.
​
from_number
string
The caller ID used, echoed from your request.
​
created_at
string
ISO 8601 timestamp recording when the call was queued.
200 OK
{
  "call_id": "call_01HXYZ123456",
  "status": "queued",
  "agent_id": "agent_abc123",
  "to_number": "+14155550100",
  "from_number": "+18005551234",
  "created_at": "2025-01-15T14:23:00Z"
}

​
Tracking call outcomes

After a call completes, VoiceInfra sends a call.completed webhook event to your configured endpoint. The webhook payload includes the call_id from this response, along with the transcript, recording URL, call outcome, and any data extracted by the agent. Store the call_id immediately after initiating a call so you can reliably match it to the incoming webhook event.

Webhooks Reference

Full payload schema, signature verification, and delivery behaviour.

Webhooks Setup Guide

Configure your webhook endpoint and monitor delivery logs.

​
Dynamic per-call configuration

The context and variables fields let you tailor agent behaviour for every individual call without touching the agent’s permanent configuration. This means one agent can handle thousands of personalised conversations — each shaped by the data you pass at call time. Common use cases:
  • Inject CRM data — pass the contact’s name, company, deal stage, or account notes so the agent speaks to them specifically
  • Personalise the greeting — use first_message to open with the caller’s name and the purpose of the call
  • Set call-specific context — pass an appointment ID, order number, or policy reference so the agent can reference it naturally during the conversation
Variables you pass in the variables object are available in your agent’s prompt template. Define the variable names in your agent configuration first, then populate them dynamically via the API.

​
Code examples

Node.js
const response = await fetch('https://api.voiceinfra.ai/v1/calls/outbound', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.VOICEINFRA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_id: 'agent_abc123',
    from_number: '+18005551234',
    to_number: '+14155550100',
    variables: { name: 'Sarah', company: 'Acme Corp' },
  }),
});
const data = await response.json();
console.log('Call ID:', data.call_id);
Python
import os
import requests

response = requests.post(
    'https://api.voiceinfra.ai/v1/calls/outbound',
    headers={
        'X-API-Key': os.environ['VOICEINFRA_API_KEY'],
        'Content-Type': 'application/json',
    },
    json={
        'agent_id': 'agent_abc123',
        'from_number': '+18005551234',
        'to_number': '+14155550100',
        'variables': {'name': 'Sarah', 'company': 'Acme Corp'},
    }
)
data = response.json()
print('Call ID:', data['call_id'])

​
Error handling

StatusCodeCauseFix
422invalid_phoneto_number or from_number is not in E.164 formatReformat the number, e.g. +14155550100
404not_foundThe agent_id does not exist or is inactiveVerify the agent ID in the API tab of your agent settings
401unauthorizedAPI key is missing, invalid, or revokedCheck the X-API-Key header and regenerate the key if needed
Always validate phone numbers to E.164 format in your application before calling the API to avoid 422 errors. Most phone number libraries (such as libphonenumber-js for Node.js or phonenumbers for Python) can handle this formatting automatically.