Error
A valid request URL is required to generate request examples{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}AI Phone Calls
Call Contact
Initiate an AI-powered phone call to a contact for automated collections and communication
POST
/
ai
/
phone-calls
/
action
/
call
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
- Automated Collections: AI can handle payment reminders and negotiate payment terms
- Customer Communication: Handle routine customer inquiries without human intervention
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
numberToCall | string | Yes | Phone number to call. A contact is automatically created if one doesn’t exist. |
firstName | string | No | Contact’s first name (used when creating or updating the contact) |
lastName | string | No | Contact’s last name (used when creating or updating the contact) |
email | string | No | Contact’s email address (used when creating or updating the contact) |
contactUuid | string (UUID) | No | Explicitly link the call to a specific contact |
aiSettingsTemplateId | string (UUID) | No | AI settings template ID for customizing call behavior |
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. |
updateExisting | boolean | No | When true, updates firstName, lastName, and email if an existing contact is found |
Response
Returns a 201 status on successful initiation of the call.AI Call Features
The AI calling system includes:- Natural Conversation: Advanced voice AI that understands context and responds naturally
- Customizable Scripts: Use
aiSettingsTemplateIdto customize the conversation flow - Call Recording: All calls are recorded for quality assurance and compliance
- Smart Routing: Intelligently routes to human agents when needed
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 the call is initiated, each {{key}} is replaced with the corresponding value from promptTags.
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.
{
"numberToCall": "+1234567890",
"firstName": "John",
"aiSettingsTemplateId": "550e8400-e29b-41d4-a716-446655440000",
"promptTags": {
"amount": "$500.00",
"due_date": "January 15, 2026"
}
}
You are a collections agent. The customer owes $500.00 due by January 15, 2026.
Be professional and offer payment plan options if the customer cannot pay in full.
Adding Guardrails
You can also use promptTags to inject additional instructions dynamically:{
"numberToCall": "+1234567890",
"firstName": "Jane",
"aiSettingsTemplateId": "550e8400-e29b-41d4-a716-446655440000",
"promptTags": {
"amount": "$1,200.00",
"due_date": "February 1, 2026",
"guardrail": "Do not mention late fees. If the customer asks about penalties, redirect to their account portal."
}
}
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
Required string length:
1 - 100Key-value pairs injected as template variables into system/knowledge base prompt.
ISO 3166-1 alpha-2 region code (e.g. 'SA', 'US') to parse local numbers.
Required string length:
2Pattern:
^[A-Z]{2}$Response
Successful Response