Error
A valid request URL is required to generate request examples{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}AI Phone Calls
Call Contact Bulk
Initiate bulk AI-powered phone calls to multiple contacts simultaneously
POST
/
ai
/
phone-calls
/
action
/
call-bulk
Error
A valid request URL is required to generate request examples{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorization
All endpoints require Bearer token authentication.| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer authentication header of the form Bearer <token> |
Getting Your API Key
See the Quickstart guide for instructions on obtaining your API credentials.Use Cases
- Mass Collections Campaigns: Send AI-powered payment reminders to many contacts at once
- Batch Customer Outreach: Handle routine communication across your contact database efficiently
- Scalable Follow-ups: Follow up on overdue invoices at scale with personalized conversations
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
contacts | array | Yes | List of contact objects to call. Each requires numberToCall. See Contact Object. |
aiSettingsTemplateId | string (UUID) | No | AI settings template ID for customizing call behavior (applied to all contacts) |
updateExisting | boolean | No | When true, updates firstName, lastName, and email if an existing contact is found. Default: false |
countryCode | string | No | ISO 3166-1 alpha-2 region code (e.g. ‘SA’, ‘US’) to parse local numbers |
batchSize | integer | No | Batch size for processing contacts. Must be between 10 and 1000. Overrides environment variable if provided |
Contact Object
Each object in thecontacts array:
| Parameter | Type | Required | Description |
|---|---|---|---|
numberToCall | string | Yes | Phone number to call |
firstName | string | No | Contact’s first name |
lastName | string | No | Contact’s last name |
metadata | object | No | Extra payload data included in webhook responses as requestMetadata |
promptTags | object | No | Key-value pairs for variable substitution in the system prompt template. See Prompt Tags. |
Response
Returns a 201 status on successful initiation of all calls.Example Request
{
"aiSettingsTemplateId": "550e8400-e29b-41d4-a716-446655440000",
"countryCode": "SA",
"updateExisting": true,
"batchSize": 50,
"contacts": [
{
"numberToCall": "+966500000001",
"firstName": "Ahmed",
"lastName": "Al-Rashid",
"metadata": {
"invoiceNumber": "INV-001",
"amount": "5000.00"
},
"promptTags": {
"amount": "5,000 SAR",
"due_date": "January 15, 2026"
}
},
{
"numberToCall": "+966500000002",
"firstName": "Sara",
"lastName": "Mohammed",
"metadata": {
"invoiceNumber": "INV-002",
"amount": "3200.00"
},
"promptTags": {
"amount": "3,200 SAR",
"due_date": "January 20, 2026"
}
}
]
}
Prompt Tags
promptTags is an optional object of key-value pairs used for template variable substitution in the system prompt. Each key maps to a placeholder in your prompt template, and the value replaces it before the call starts.
This is separate from metadata — metadata is stored on the call log and included in webhooks, while promptTags is consumed at call time to populate the system prompt.
How It Works
Your system prompt template uses{{key}} placeholders. When each call is initiated, the {{key}} from that contact’s promptTags is replaced.
System prompt template:
You are a collections agent. The customer owes {{amount}} due by {{due_date}}.
Be professional and offer payment plan options if the customer cannot pay in full.
{
"amount": "5,000 SAR",
"due_date": "January 15, 2026"
}
You are a collections agent. The customer owes 5,000 SAR due by January 15, 2026.
Be professional and offer payment plan options if the customer cannot pay in full.
Prompt Tags vs Metadata
| Field | Purpose | Where It Goes |
|---|---|---|
promptTags | Variable substitution in the system prompt template | Consumed at call time, injected into the prompt |
metadata | Arbitrary data attached to the call record | Stored on call log, included in webhook payloads as requestMetadata |
Authorizations
Enter JWT token obtained from authentication endpoint. Format: Bearer <your_token>
Body
application/json
Show child attributes
Show child attributes
ISO 3166-1 alpha-2 region code (e.g. 'SA', 'US') to parse local numbers.
Required string length:
2Pattern:
^[A-Z]{2}$Batch size for processing contacts. Must be between 10 and 1000. Overrides environment variable if provided.
Response
Successful Response