Skip to main content
POST
/
call
/
outbound
curl --request POST \
  --url https://api.callkaro.ai/call/outbound \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "to_number": "+919876543210",
  "agent_id": "6803fa770b666a64ab1694c1e"
}
'
{
  "status": "done",
  "message": "Call queued successfully",
  "call_sid": "a1b2c3d4e5"
}
This endpoint initiates an outbound call to a customer’s phone number using your configured AI agent.

​
Quick Example

curl -X POST https://api.callkaro.ai/call/outbound \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "to_number": "+919876543210",
    "agent_id": "6803fa770b666a64ab1694c1e"
  }'

​
Use Cases

  • Immediate calls: Trigger calls instantly
  • Scheduled calls: Schedule for specific times
  • Campaign calls: Add to existing campaigns via batch_id
  • Retry logic: Auto-retry failed calls

​
Common Scenarios

Pass customer data to your agent via the metadata field:
{
  "to_number": "+919876543210",
  "agent_id": "6803fa770b666a64ab1694c1e",
  "metadata": {
    "name": "Abhinav",
    "age": 25,
    "city": "Bangalore"
  },
  "priority": 1,
  "language": "hi"
}
Access in your agent prompt using {{metadata.name}}, {{metadata.age}}, etc.
Automatically retry if customer doesn’t answer:
{
  "to_number": "+919876543210",
  "agent_id": "6803fa770b666a64ab1694c1e",
  "number_of_retries": 3,
  "gap_between_retries": [30, 60]
}
This will retry after 30 minutes, then 60 minutes if the first retry fails.
Schedule a call for a specific date and time:
{
  "to_number": "+919876543210",
  "agent_id": "6803fa770b666a64ab1694c1e",
  "schedule_at": "2025-12-31T09:30:00"
}
Set time windows for when calls can be made:
{
  "to_number": "+919876543210",
  "agent_id": "6803fa770b666a64ab1694c1e",
  "schedule_at": "2025-12-31T09:30:00",
  "min_trigger_time": "09:00",
  "max_trigger_time": "18:00",
  "number_of_retries": 3,
  "gap_between_retries": 30
}
Calls will only trigger between 9 AM and 6 PM.
Use carry_over to reschedule missed calls:
{
  "to_number": "+919876543210",
  "agent_id": "6803fa770b666a64ab1694c1e",
  "schedule_at": "2025-12-31T09:30:00",
  "min_trigger_time": "09:00",
  "max_trigger_time": "18:00",
  "carry_over": true,
  "number_of_retries": 3,
  "gap_between_retries": 30
}
If call doesn’t complete by 6 PM, it will reschedule to next day at 9 AM.

​
Response

​
Success (200 OK)

{
  "status": "success",
  "message": "Call initiated successfully",
  "call_id": "a1b2c3d4e5"
}

​
Errors

​
400
Bad Request
Missing or invalid parameters
{"status": "error", "message": "Missing agent_id"}
​
403
Forbidden
Invalid or missing API key
{"status": "error", "message": "Missing X-API-KEY in headers"}
​
404
Not Found
Agent doesn’t exist
{"status": "error", "message": "Agent does not exist"}
​
500
Server Error
Internal server error - contact support
{"status": "error", "message": "Server error"}

Authorizations

​
X-API-KEY
string
header
required

API key from https://callkaro.ai/dashboard/api-key

Body

application/json
​
to_number
string
required

Customer's phone number in international format (E.164)

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

"+919876543210"

​
agent_id
string
required

ID of the AI agent that will handle the call

Example:

"6803fa770b666a64ab1694c1e"

​
batch_id
string

ID of the campaign this call belongs to (optional)

​
metadata
object

Custom customer data accessible in agent prompts using {{metadata.key}}

Example:
{
  "name": "John Doe",
  "age": 25,
  "city": "Bangalore"
}
​
schedule_at
string<date-time>

Scheduled call time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)

Example:

"2025-05-28T09:30:00"

​
min_trigger_time
string

Earliest time of day the call can trigger (HH:MM format)

Pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
Example:

"09:00"

​
max_trigger_time
string

Latest time of day the call can trigger (HH:MM format)

Pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
Example:

"18:00"

​
carry_over
boolean
default:false

If true, reschedule to next day if max_trigger_time is reached

​
number_of_retries
integer

Number of retry attempts if call doesn't connect successfully

Required range: 0 <= x <= 10
Example:

3

​
gap_between_retries

Same gap for all retries (in minutes)

Example:

30

​
priority
integer
default:0

Call priority in queue. Higher values = higher priority

Required range: -100 <= x <= 100
​
language
enum<string>

Language code for the call (ISO 639-1)

Available options:
hi,
en,
kn,
mr,
ta,
te,
bn,
gu,
ml
Example:

"en"

Response

Call queued successfully

​
status
string
Example:

"done"

​
message
string
Example:

"Call queued successfully"

​
call_sid
string

Unique identifier for the queued call

Example:

"a1b2c3d4e5"