Skip to main content
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.
HeaderTypeRequiredDescription
AuthorizationstringYesBearer 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

ParameterTypeRequiredDescription
contactsarrayYesList of contact objects to call. Each requires numberToCall. See Contact Object.
aiSettingsTemplateIdstring (UUID)NoAI settings template ID for customizing call behavior (applied to all contacts)
updateExistingbooleanNoWhen true, updates firstName, lastName, and email if an existing contact is found. Default: false
countryCodestringNoISO 3166-1 alpha-2 region code (e.g. ‘SA’, ‘US’) to parse local numbers
batchSizeintegerNoBatch size for processing contacts. Must be between 10 and 1000. Overrides environment variable if provided

​
Contact Object

Each object in the contacts array:
ParameterTypeRequiredDescription
numberToCallstringYesPhone number to call
firstNamestringNoContact’s first name
lastNamestringNoContact’s last name
metadataobjectNoExtra payload data included in webhook responses as requestMetadata
promptTagsobjectNoKey-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.
Per-contact promptTags (from the contacts array): 
{
  "amount": "5,000 SAR",
  "due_date": "January 15, 2026"
}
Resulting system prompt for that contact: 
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

FieldPurposeWhere It Goes
promptTagsVariable substitution in the system prompt templateConsumed at call time, injected into the prompt
metadataArbitrary data attached to the call recordStored on call log, included in webhook payloads as requestMetadata

Authorizations

​
Authorization
string
header
required

Enter JWT token obtained from authentication endpoint. Format: Bearer <your_token>

Body

application/json
​
contacts
_BulkContactSchema · object[]
required
​
aiSettingsTemplateId
string<uuid> | null
​
updateExisting
boolean
default:false
​
countryCode
string | null

ISO 3166-1 alpha-2 region code (e.g. 'SA', 'US') to parse local numbers.

Required string length: 2
Pattern: ^[A-Z]{2}$
​
batchSize
integer | null

Batch size for processing contacts. Must be between 10 and 1000. Overrides environment variable if provided.

Response

Successful Response