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

  • Automated Collections: AI can handle payment reminders and negotiate payment terms
  • Customer Communication: Handle routine customer inquiries without human intervention

​
Request Body

ParameterTypeRequiredDescription
numberToCallstringYesPhone number to call. A contact is automatically created if one doesn’t exist.
firstNamestringNoContact’s first name (used when creating or updating the contact)
lastNamestringNoContact’s last name (used when creating or updating the contact)
emailstringNoContact’s email address (used when creating or updating the contact)
contactUuidstring (UUID)NoExplicitly link the call to a specific contact
aiSettingsTemplateIdstring (UUID)NoAI settings template ID for customizing call behavior
metadataobjectNoExtra payload data included in webhook responses as requestMetadata
promptTagsobjectNoKey-value pairs for variable substitution in the system prompt template. See Prompt Tags.
updateExistingbooleanNoWhen 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 aiSettingsTemplateId to 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.
Request with promptTags: 
{
  "numberToCall": "+1234567890",
  "firstName": "John",
  "aiSettingsTemplateId": "550e8400-e29b-41d4-a716-446655440000",
  "promptTags": {
    "amount": "$500.00",
    "due_date": "January 15, 2026"
  }
}
Resulting system prompt sent to the AI: 
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

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
​
numberToCall
string
required
Required string length: 1 - 100
​
updateExisting
boolean
default:false
​
firstName
string | null
​
lastName
string | null
​
email
string | null
​
metadata
Metadata · object | null
​
promptTags
Prompttags · object | null

Key-value pairs injected as template variables into system/knowledge base prompt.

​
contactUuid
string<uuid> | null
​
aiSettingsTemplateId
string<uuid> | null
​
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}$

Response

Successful Response