Skip to main content
POST
Initiate outbound call

Overview

Initiate a new outbound phone call using an AI agent. The agent will automatically handle the conversation based on its configuration.

Request Body

string
required
Phone number to call in E.164 format (e.g., +1234567890)
string
ID of the AI agent to use for the call. Required if instruction is not provided.
string
AI agent instruction/prompt. Used to create a temporary agent if agent_id is not provided. Required if agent_id is not provided.
string
Optional webhook URL to receive call completion notifications. Must be a valid HTTP/HTTPS URL.
string
Optional external call ID for tracking purposes.
string
Optional input parameters as JSON string to pass to the agent.
string
Optional output parameters template as JSON string to extract structured data from the conversation.
string
Existing call ID to retrieve status for. If provided, a new call will not be created.

Example Request

Response

boolean
Whether the request was successful
string
Unique identifier for the call
string
Current status of the call. Initially RINGING when call is initiated.
string
Response message

Example Response

Error Responses

boolean
Always false for errors
string
Human-readable error message
string
Error code. Possible values: MISSING_PARAMS, AGENT_NOT_FOUND, INSUFFICIENT_BALANCE, INTERNAL_ERROR

Webhooks

If you provide a webhook_url, you’ll receive a POST request when the call completes with the following data:

Billing

Calls are billed at $0.15 per minute with precise second-by-second billing. Ensure your account has sufficient balance before making calls.

Authorizations

Authorization
string
header
required

API key authentication. Include your API key in the Authorization header as: Bearer YOUR_API_KEY

Body

application/json

Call request parameters

to_phone_number
string
required

Phone number to call (E.164 format, e.g., +1234567890)

Pattern: ^\+[1-9]\d{1,14}$
call_id
string

Existing call ID to retrieve status for

agent_id
string

ID of the AI agent to use for the call. Required if instruction is not provided.

instruction
string

AI agent instruction/prompt. Used to create a temporary agent if agent_id is not provided.

webhook_url
string<uri>

Optional webhook URL to receive call completion notifications

external_call_id
string

Optional external call ID for tracking

input_parameters
string

Optional input parameters as JSON string

output_parameters
string

Optional output parameters template as JSON string

Response

Call initiated successfully

success
boolean
required

Whether the request was successful

call_id
string
required

Unique identifier for the call

status
enum<string>
required

Current status of the call

Available options:
IDLE,
RINGING,
IN_PROGRESS,
COMPLETED,
FAILED
message
string

Response message