Skip to main content
Initiate Call(s)
curl --request POST \
  --url https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "<string>",
  "dispositionId": "<string>",
  "limit": 123,
  "filters": {
    "ids": [
      "<string>"
    ],
    "exclude_ids": [
      "<string>"
    ],
    "payment_status": [
      "<string>"
    ],
    "language": [
      "<string>"
    ],
    "custom": {}
  }
}
'
{
  "success": true,
  "message": "Calls initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

​
Headers

​
Authorization
string
required
Bearer token for authentication (e.g., Bearer <your_token>).

​
Path Parameters

​
campaignId
string
required
The campaign ID containing the customers to call.

​
Body Parameters

​
agentId
string
required
AI agent ID to handle the calls.
​
dispositionId
string
required
Disposition ID for call categorization.
​
limit
integer
Maximum number of customers to call. If omitted, all matching customers are called.
​
filters
object
Optional filters to target specific customers. If omitted, all customers in the campaign are called. Multiple filters are combined with AND logic.

​
Response

​
success
boolean
true if all calls were initiated successfully, false otherwise.
​
message
string
Summary of the operation result.
​
results
object
Detailed breakdown of the call initiation.
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
{
  "success": true,
  "message": "Calls initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

​
Usage Examples

Call all customers in a campaign: 
{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789"
}
Call only bounced and pending customers: 
{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789",
  "filters": {
    "payment_status": ["bounced", "pending"]
  }
}
Call customers with EMI due this month, limited to 100: 
{
  "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: 
{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789",
  "filters": {
    "ids": ["LOAN-2025-00123", "LOAN-2025-00456", "LOAN-2025-00789"]
  }
}
Call with custom field filters: 
{
  "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: 
{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789",
  "filters": {
    "exclude_ids": ["LOAN-2025-00789", "LOAN-2025-00999"]
  }
}