POST /outbound_call — Place an AI Call

POST /outbound_call places a call from one of your AI agents. Trigger it from a CRM when a lead is created, from an automation platform when a form is submitted, or from your own application when something happens. You can shape the call — extra context, dynamic variables, an opening line — without editing the agent.

POST https://<your-region-host>/api/v1/outbound_call

Before you can place a call

Requirement	Detail
An API key	From the API Keys page. See API Keys.
A fully verified account	Outbound calling requires full account verification, not just phone verification. Until then the API refuses to place calls.
A phone number with an outbound trunk	The number you call from must be configured for outbound. You pass its ID, not the number itself.
An agent	Any agent in the workspace. Its ID is shown on the agent’s API tab.

Outbound calling is blocked until the workspace owner is fully verified. If calls fail for an account that has only verified its phone number, this is why. See Account verification.

Request headers

string

required

Your VoiceInfra API key.

string

required

Must be application/json.

Request body

string

required

The ID of the agent that should make the call. Find it on the agent’s API tab.

string

required

The number to call, in E.164 format — for example +14155551234.

string

required

The ID of the phone number the call goes out from — a UUID, not the number in E.164. The number must be configured for outbound in your workspace.

string

Extra context for the agent on this call only. Use it for anything that should shape the conversation but does not fit a variable — for example “Sarah prefers short calls and has an outstanding balance from her last visit.”

object

Key-value pairs that fill {{placeholders}} in the agent’s prompt and opening message. For example {"name": "Sarah Johnson", "order_id": "4521"}.

string

Overrides the agent’s opening line for this call. Not available on workflow agents — a workflow agent’s greeting comes from its start node, and the API rejects the request if you send this field.

Example body

{
  "agent_id": "your-agent-uuid",
  "phone_number": "+14155551234",
  "from_number_id": "your-phone-number-uuid",
  "additional_context": "Customer prefers brief calls.",
  "context_variables": {
    "name": "John Smith",
    "company": "Acme Corp",
    "order_id": "4521"
  },
  "first_message": "Hi {{name}}, calling about order {{order_id}}."
}

Response

A successful request returns 200:

{
  "status": "success",
  "message": "Outbound call initiated successfully",
  "agent_id": "your-agent-uuid",
  "agent_name": "Bright Smile Receptionist",
  "call_details": {
    "sip_call_id": "a7f3c1e2-...",
    "from_number_id": "your-phone-number-uuid",
    "phone_number": "+14155551234",
    "call_type": "dynamic-outbound"
  }
}

Field	Meaning
`status`	`success` when the call was accepted
`message`	Human-readable confirmation
`agent_id`	The agent that is making the call
`agent_name`	That agent’s name
`call_details.sip_call_id`	Identifier for this call leg — store this to correlate with the call log and webhook
`call_details.from_number_id`	Echoed from your request
`call_details.phone_number`	Echoed from your request
`call_details.call_type`	Always `dynamic-outbound` for API-placed calls

status: "success" means the call was initiated, not that anyone answered. Whether it connected, and how it went, arrives in the webhook and on the call log.

Unknown fields are rejected

The request body is strict — sending a field that is not in the list above returns 422. If you are adapting an older example, check the field names: phone_number and from_number_id, not to_number and from_number.

Filling in variables

context_variables are substituted into the agent’s system prompt and opening message wherever a matching {{placeholder}} appears. Built-in values are available too, so you only pass what is specific to the call.

Placeholder	Value
`{{name}}`, `{{order_id}}`, …	Whatever you put in `context_variables`
`{{current_date}}`	Today’s date, in the agent’s configured timezone
`{{current_time}}`	The current time
`{{from_number}}`	The number the call goes out from
`{{to_number}}`	The number being called

A prompt like this:

You are calling {{name}} about their appointment with {{doctor}} on {{appointment_time}}.
Today is {{current_date}}.

resolves at call time to:

You are calling Sarah Johnson about their appointment with Dr. Lee on Feb 18 at 2:30 PM.
Today is Monday, February 17, 2026.

Sending the request

cURL

curl -X POST "https://<your-region-host>/api/v1/outbound_call" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vk_YOUR_API_KEY" \
  -d '{
    "agent_id": "your-agent-uuid",
    "phone_number": "+14155551234",
    "from_number_id": "your-phone-number-uuid",
    "additional_context": "Customer prefers brief calls.",
    "context_variables": { "name": "John Smith", "order_id": "4521" }
  }'

Tracking the outcome

VoiceInfra sends a call_completed webhook to your configured endpoint when the call ends, carrying the call_id from this response. Store that ID immediately so you can match the two. If a webhook is missed, GET /agents/active-calls tells you whether the call is still running — see Active Calls.

Active Calls

Check whether a call is still in progress.

Webhooks Reference

Payload schema and signature verification.

Errors

Status	Likely cause
`401`	Missing or invalid API key
`403`	Workspace suspended, or the owner is not fully verified
`422`	A field failed validation — E.164 formatting, or `first_message` sent to a workflow agent
`404`	`agent_id` or `from_number_id` does not exist in this workspace
`429`	Rate limited — outbound calls are limited more tightly than reads

Overview

Endpoints

MCP & Apps

POST /outbound_call — Place an AI Call

Before you can place a call

Request headers

Request body

Example body

Response

Unknown fields are rejected

Filling in variables

Sending the request

Tracking the outcome

Active Calls

Webhooks Reference

Errors

​Before you can place a call

​Request headers

​Request body

​Example body

​Response

​Unknown fields are rejected

​Filling in variables

​Sending the request

​Tracking the outcome

Active Calls

Webhooks Reference

​Errors

Before you can place a call

Request headers

Request body

Example body

Response

Unknown fields are rejected

Filling in variables

Sending the request

Tracking the outcome

Errors