Skip to main content
POST
/
api
/
outbound
Create Outbound Call
curl --request POST \
  --url https://allomia.com/api/outbound \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phoneNumber": "<string>",
  "assistantId": "<string>",
  "phoneNumberId": "<string>",
  "customerName": "<string>",
  "dynamicVariables": {},
  "callbackUrl": "<string>"
}
'
{
  "outboundCallId": "<string>",
  "contactId": "<string>",
  "status": "<string>",
  "message": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.allomia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Create Outbound Call

Triggers a single outbound call to a phone number using the specified AI assistant. The call is dispatched immediately upon receiving the request. Requires a tenant or organization-level API key for authentication.

​
Headers

​
Authorization
string
required
API key is required. Enter either your tenant-specific or organization-specific API key in the format Bearer YOUR-API-KEY

​
Body Parameters

​
phoneNumber
string
required
Phone number to call. E.164 format is recommended (e.g. +15145551234). Must be between 10 and 20 characters.
​
assistantId
string
required
UUID of the AI assistant to use for the call. The assistant must belong to the organization associated with the API key.
​
phoneNumberId
string
required
UUID of the AlloMia phone number to call from. The phone number must belong to the organization associated with the API key.
​
customerName
string
Name of the person being called. When provided, the AI assistant can use this to personalize the conversation.
​
dynamicVariables
object
Key-value pairs passed as dynamic variables to the AI assistant at call time. Values must be strings. These allow the assistant to personalize the conversation based on contextual information (e.g., patient name, appointment slot, practitioner name).
{
  "patientId": "12345",
  "appointmentSlot": "2026-04-01T10:00:00Z",
  "practitioner": "Dr. Smith"
}
​
callbackUrl
string
A URL to receive a POST webhook request when the call reaches a terminal state (completed, failed, busy, or no-answer). The payload will mirror the Get Outbound Call Status response.

​
Response

​
outboundCallId
string
UUID uniquely identifying this outbound call record. Use this ID to poll Get Outbound Call Status and track the call’s progress.
​
contactId
string
UUID of the contact record created for this outbound call.
​
status
string
Initial status of the call. Always calling on success, indicating the call has been dispatched.
​
message
string
Human-readable description of the dispatched status (e.g., "Outbound call dispatched").

​
Example Request

curl -X POST https://allomia.com/api/outbound \
  -H "Authorization: Bearer YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15145551234",
    "assistantId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
    "phoneNumberId": "b2c3d4e5-f6a7-8901-bcde-234567890123",
    "customerName": "John Doe",
    "dynamicVariables": {
      "patientId": "12345",
      "appointmentSlot": "2026-04-01T10:00:00Z",
      "practitioner": "Dr. Smith"
    },
    "callbackUrl": "https://partner.example.com/webhooks/call-status"
  }'

​
Example Response

{
  "outboundCallId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "contactId": "d4e5f6a7-b8c9-0123-defa-456789012345",
  "status": "calling",
  "message": "Outbound call dispatched"
}

​
Error Responses

Returned when the request body fails validation. The details array lists each field-level error.
{
  "error": "Invalid request data",
  "details": [
    {
      "field": "phoneNumber",
      "message": "Phone number must be at least 10 digits",
      "code": "too_small"
    }
  ]
}
Returned when the API key is missing or invalid.
{
  "error": "Invalid or missing API key"
}
Returned when the API key does not have the required permissions to trigger outbound calls.
{
  "error": "Insufficient permissions"
}
Returned when the specified assistant or phone number does not exist or does not belong to the organization.
{
  "error": "Assistant or phone number not found"
}
Returned when the organization associated with the API key is inactive.
{
  "error": "Organization is inactive"
}

{
  "error": "Internal server error occurred"
}