Skip to main content

​
Trigger AI Phone Call

Initiate an AI-powered phone call by providing a phone number. The API can automatically create a contact record if one doesn’t exist, or you can reference an existing contact. 
# Basic call - phone number only
# (auto-creates contact with only the phone number)
curl --request POST \
--url https://api.dev.uselevers.com/api-service/v1/ai/phone-calls/action/call \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "numberToCall": "+96612341234",
  "metadata": {
    "project_id": "proj_123",
    "extra_id": "custom_id_456"
  }
}'

# With contact details (auto-creates contact with more information)
curl --request POST \
--url https://api.dev.uselevers.com/api-service/v1/ai/phone-calls/action/call \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "numberToCall": "+96612341234",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "metadata": {
    "project_id": "proj_123",
    "extra_id": "custom_id_456"
  }
}'

# Tries to link the phone number to a pre-existing contact with the UUID
curl --request POST \
--url https://api.dev.uselevers.com/api-service/v1/ai/phone-calls/action/call \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "numberToCall": "+96612341234",
  "contactUuid": "9bfa828a-3c2d-430c-bdc7-f74d90334524",
  "metadata": {
    "project_id": "proj_123",
    "extra_id": "custom_id_456"
  }
}'

# With custom AI settings template
curl --request POST \
--url https://api.dev.uselevers.com/api-service/v1/ai/phone-calls/action/call \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "numberToCall": "+96612341234",
  "firstName": "John",
  "lastName": "Doe",
  "aiSettingsTemplateId": "template-uuid-here",
  "metadata": {
    "project_id": "proj_123",
    "extra_id": "custom_id_456"
  }
}'

# Disable auto-create contact
curl --request POST \
--url https://api.dev.uselevers.com/api-service/v1/ai/phone-calls/action/call \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "numberToCall": "+96612341234",
  "createIfNotExists": false,
  "metadata": {
    "project_id": "proj_123",
    "extra_id": "custom_id_456"
  }
}'

​
Request Fields

​
numberToCall
string
required
Phone number to call. We automatically search for any existing contact with this number to avoid creating duplicates.
​
createIfNotExists
boolean
default:"true"
When true, automatically creates a contact if one cannot be found. When false, only calls existing contacts (returns a 404 error if the contact doesn’t exist).
​
contactDetails
Contact Details
​
contactUuid
string (UUID)
Explicitly link the call to a specific contact. This is useful when calling a contact at a different number than their default one—the numberToCall is still dialed, but the call is associated with the specified contact. If the UUID doesn’t exist, we’ll fall back to searching by phone number and potentially creating a new contact (depending on the createIfNotExists setting).
​
aiSettingsTemplateId
string (UUID)
Customize how the AI behaves during the call using your prompt templates from the Levers app. If not specified, the default template will be used.
​
metadata
object
Optional field for sending extra payload data with the call. This metadata will be included in webhook responses as requestMetadata, allowing you to track additional context like project_id, extra_id, or any custom key-value pairs relevant to your application.