Skip to main content
POST
/
outbound_call
Initiate outbound call
curl --request POST \
  --url https://api.call24x7.ai/outbound_call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to_phone_number": "<string>",
  "call_id": "<string>",
  "agent_id": "<string>",
  "instruction": "<string>",
  "webhook_url": "<string>",
  "external_call_id": "<string>",
  "input_parameters": "<string>",
  "output_parameters": "<string>"
}
'
{
  "success": true,
  "call_id": "<string>",
  "message": "<string>"
}

​
Overview

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

​
Request Body

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

​
Example Request

curl -X POST https://api.call24x7.ai/outbound_call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone_number": "+1234567890",
    "agent_id": "agent-123"
  }'

​
Response

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

​
Example Response

{
  "success": true,
  "call_id": "12345",
  "status": "RINGING",
  "message": "Call initiated successfully"
}

​
Error Responses

​
success
boolean
Always false for errors
​
message
string
Human-readable error message
​
error_code
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: 
{
  "call_id": "12345",
  "status": "COMPLETED",
  "call_direction": "outbound",
  "from_phone_number": "+1234567890",
  "to_phone_number": "+0987654321",
  "agent_id": "agent-123",
  "duration_seconds": 180,
  "recording_url": "https://...",
  "transcription": "Full call transcription...",
  "output_parameters": "{\"appointment_scheduled\": true}"
}

​
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