> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callkaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Outbound Call
> Initiate an outbound call to a customer with scheduling and retry capabilities
This endpoint initiates an outbound call to a customer's phone number using your configured AI agent.
## Quick Example
```bash theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"to_number": "+919876543210",
"agent_id": "6803fa770b666a64ab1694c1e",
"schedule_at": "2025-12-31T09:30:00"
}
```
Set time windows for when calls can be made:
```json theme={null}
{
"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:
```json theme={null}
{
"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)
```json theme={null}
{
"status": "success",
"message": "Call initiated successfully",
"call_id": "a1b2c3d4e5"
}
```
### Errors
Missing or invalid parameters
```json theme={null}
{"status": "error", "message": "Missing agent_id"}
```
Invalid or missing API key
```json theme={null}
{"status": "error", "message": "Missing X-API-KEY in headers"}
```
Agent doesn't exist
```json theme={null}
{"status": "error", "message": "Agent does not exist"}
```
Internal server error - contact support
```json theme={null}
{"status": "error", "message": "Server error"}
```
## OpenAPI
````yaml POST /call/outbound
openapi: 3.1.0
info:
title: CallKaro AI API
description: Campaign and outbound call management API for CallKaro AI voice agents
version: 1.0.0
contact:
name: CallKaro AI Support
email: support@callkaro.ai
url: https://callkaro.ai
servers:
- url: https://api.callkaro.ai
description: Production server
security:
- ApiKeyAuth: []
paths:
/call/outbound:
post:
tags:
- Endpoints
summary: Create Outbound Call
description: >-
Initiate an outbound call to a customer with scheduling and retry
capabilities
operationId: createOutboundCall
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OutboundCallRequest'
examples:
basic:
summary: Basic outbound call
value:
to_number: '+919876543210'
agent_id: 6803fa770b666a64ab1694c1e
scheduled:
summary: Scheduled call with metadata
value:
to_number: '+919876543210'
agent_id: 6803fa770b666a64ab1694c1e
schedule_at: '2025-05-28T09:30:00'
metadata:
name: John Doe
city: Bangalore
withRetries:
summary: Call with retry logic
value:
to_number: '+919876543210'
agent_id: 6803fa770b666a64ab1694c1e
number_of_retries: 3
gap_between_retries: 30
min_trigger_time: '09:00'
max_trigger_time: '18:00'
responses:
'200':
description: Call queued successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OutboundCallResponse'
example:
status: done
message: Call queued successfully
call_sid: a1b2c3d4e5
'400':
description: Bad request - Missing or invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: error
message: 'Missing required field: to_number'
'403':
description: Forbidden - Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: error
message: Invalid or missing API key
components:
schemas:
OutboundCallRequest:
type: object
required:
- to_number
- agent_id
properties:
to_number:
type: string
description: Customer's phone number in international format (E.164)
example: '+919876543210'
pattern: ^\+[1-9]\d{1,14}$
agent_id:
type: string
description: ID of the AI agent that will handle the call
example: 6803fa770b666a64ab1694c1e
batch_id:
type: string
description: ID of the campaign this call belongs to (optional)
metadata:
type: object
description: >-
Custom customer data accessible in agent prompts using
{{metadata.key}}
example:
name: John Doe
age: 25
city: Bangalore
schedule_at:
type: string
format: date-time
description: Scheduled call time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
example: '2025-05-28T09:30:00'
min_trigger_time:
type: string
description: Earliest time of day the call can trigger (HH:MM format)
example: '09:00'
pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
max_trigger_time:
type: string
description: Latest time of day the call can trigger (HH:MM format)
example: '18:00'
pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
carry_over:
type: boolean
default: false
description: If true, reschedule to next day if max_trigger_time is reached
number_of_retries:
type: integer
minimum: 0
maximum: 10
description: Number of retry attempts if call doesn't connect successfully
example: 3
gap_between_retries:
oneOf:
- type: integer
description: Same gap for all retries (in minutes)
- type: array
items:
type: integer
description: Different gaps per retry (in minutes)
example: 30
priority:
type: integer
minimum: -100
maximum: 100
default: 0
description: Call priority in queue. Higher values = higher priority
language:
type: string
enum:
- hi
- en
- kn
- mr
- ta
- te
- bn
- gu
- ml
description: Language code for the call (ISO 639-1)
example: en
OutboundCallResponse:
type: object
properties:
status:
type: string
example: done
message:
type: string
example: Call queued successfully
call_sid:
type: string
description: Unique identifier for the queued call
example: a1b2c3d4e5
ErrorResponse:
type: object
properties:
status:
type: string
example: error
message:
type: string
description: Error description
example: 'Missing required field: to_number'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: API key from https://callkaro.ai/dashboard/api-key
````