> ## Documentation Index
> Fetch the complete documentation index at: https://agents.docs.timepay.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate Call(s)
> Initiate AI agent calls for customers in a campaign with optional filters to target specific subsets.
### Headers
Bearer token for authentication (e.g., `Bearer `).
### Path Parameters
The campaign ID containing the customers to call.
### Body Parameters
AI agent ID to handle the calls.
Disposition ID for call categorization.
Maximum number of customers to call. If omitted, all matching customers are called.
Optional filters to target specific customers. If omitted, all customers in the campaign are called. Multiple filters are combined with **AND** logic.
Call only these specific customer IDs (`loan_id` or `lead_id`).
Exclude these customer IDs from calling.
Filter by payment status. Accepts a single value or an array.
* `bounced` — Payment was attempted but failed.
* `pending` — Payment is due but not yet initiated.
* `partial` — Customer has made a partial payment.
* `paid` — Payment has been completed.
* `received` — Payment has been received and confirmed.
Filter by customer language preference. Accepts a single value or an array (e.g., `"hindi"` or `["hindi", "english"]`).
Custom field exact-match filters as key-value pairs. Values can be a single string or an array of strings.
```json Example theme={null}
{
"branch": "mumbai",
"product_type": ["personal_loan", "home_loan"]
}
```
### Response
`true` if all calls were initiated successfully, `false` otherwise.
Summary of the operation result.
Detailed breakdown of the call initiation.
Total customers matching the query/filters in the campaign.
Customers selected for calling (respects `limit` if provided).
Calls successfully initiated.
Calls that failed to initiate.
Number of call batches processed (500 customers per batch).
Array of error objects for failed batches.
Batch number that failed.
Error type.
Human-readable error reason.
Number of customers affected in the failed batch.
**Response Status Codes:**
* `200` — All calls initiated successfully
* `207` — Partial success (some calls initiated, some failed)
* `400` — Validation error, no active numbers, or missing agent variables
* `404` — Campaign, agent, or customers not found
* `500` — All calls failed or internal server error
```json 200 All Calls Initiated theme={null}
{
"success": true,
"message": "Calls initiated for 250 customers",
"results": {
"totalMatched": 500,
"customersSelected": 250,
"initiated": 250,
"failed": 0,
"batchesProcessed": 1,
"errors": []
}
}
```
```json 207 Partial Success theme={null}
{
"success": false,
"message": "Calls initiated for 200 of 250 customers",
"results": {
"totalMatched": 500,
"customersSelected": 250,
"initiated": 200,
"failed": 50,
"batchesProcessed": 1,
"errors": [
{
"batch": 1,
"error": "Call initiation failed",
"reason": "Workflow runner timeout",
"affectedCustomers": 50
}
]
}
}
```
```json 400 Validation Error theme={null}
{
"success": false,
"message": "Validation failed",
"errors": [
"agentId is required and must be a string"
]
}
```
```json 400 No Active Numbers theme={null}
{
"success": false,
"message": "No active numbers available for this organization"
}
```
```json 400 Missing Agent Variables theme={null}
{
"success": false,
"message": "Cannot initiate calls: Missing variables: emi_due_date, loan_amount",
"totalMatched": 250,
"customersSelected": 250
}
```
```json 404 Campaign Not Found theme={null}
{
"success": false,
"message": "Campaign not found"
}
```
```json 404 Agent Not Found theme={null}
{
"success": false,
"message": "Agent not found"
}
```
```json 404 No Customers Found theme={null}
{
"success": false,
"message": "No customers found matching the given filters"
}
```
```json 403 Forbidden theme={null}
{
"success": false,
"message": "Campaign ID invalid or mismatch for your organization."
}
```
```json 500 Server Error theme={null}
{
"success": false,
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}
```
### Usage Examples
**Call all customers in a campaign:**
```json theme={null}
{
"agentId": "agent_abc123",
"dispositionId": "disp_xyz789"
}
```
**Call only bounced and pending customers:**
```json theme={null}
{
"agentId": "agent_abc123",
"dispositionId": "disp_xyz789",
"filters": {
"payment_status": ["bounced", "pending"]
}
}
```
**Call customers with EMI due this month, limited to 100:**
```json theme={null}
{
"agentId": "agent_abc123",
"dispositionId": "disp_xyz789",
"limit": 100,
"filters": {
"emi_due_date": {
"from": "2025-08-01",
"to": "2025-08-31"
},
"payment_status": "pending"
}
}
```
**Call specific customers by ID:**
```json theme={null}
{
"agentId": "agent_abc123",
"dispositionId": "disp_xyz789",
"filters": {
"ids": ["LOAN-2025-00123", "LOAN-2025-00456", "LOAN-2025-00789"]
}
}
```
**Call with custom field filters:**
```json theme={null}
{
"agentId": "agent_abc123",
"dispositionId": "disp_xyz789",
"filters": {
"payment_status": ["bounced", "pending"],
"emi_amount": {
"min": 5000,
"max": 20000
},
"language": "hindi",
"custom": {
"branch": "mumbai",
"product_type": ["personal_loan", "home_loan"]
}
}
}
```
**Call all customers except specific ones:**
```json theme={null}
{
"agentId": "agent_abc123",
"dispositionId": "disp_xyz789",
"filters": {
"exclude_ids": ["LOAN-2025-00789", "LOAN-2025-00999"]
}
}
```