Skip to main content

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.

​
Overview

The Outbound Calls API allows you to programmatically trigger AI-powered outbound phone calls to any contact and monitor their status in real time. These endpoints require either a tenant-level or organization-level API key for authentication.

​
Available Endpoints

Create Outbound Call

Trigger an immediate outbound call to a phone number using a specified AI assistant

Get Outbound Call Status

Retrieve the current status and details of a previously created outbound call

​
Authentication

All Outbound Call API endpoints require a tenant-level or organization-level API key in the format: 
Authorization: Bearer YOUR-API-KEY
For more information on authentication, see the Authentication guide.

​
How It Works

  1. Create a call — Send a POST /api/outbound request with the target phone number, AI assistant ID, and outbound phone number ID. The call is dispatched immediately and you receive an outboundCallId in the response.
  2. Monitor the call — Poll GET /api/outbound/{id}/status using the outboundCallId to track the call’s progress. The status transitions from calling to a terminal state (completed, failed, busy, or no-answer).
  3. Receive a webhook (optional) — If you provide a callbackUrl when creating the call, AlloMia will send a POST request to that URL when the call reaches a terminal state.

​
Data Structures

​
Outbound Call Request

FieldTypeRequiredDescription
phoneNumberstringYesPhone number to call in E.164 format (e.g. +15145551234)
assistantIdstringYesUUID of the AI assistant to use for the call
phoneNumberIdstringYesUUID of the AlloMia phone number to call from
customerNamestringNoName of the person being called
dynamicVariablesobjectNoKey-value pairs passed as dynamic variables to the AI assistant at call time
callbackUrlstringNoURL to receive a POST webhook when the call reaches a terminal state

​
Outbound Call Response

FieldTypeDescription
outboundCallIdstringUUID identifying this outbound call record
contactIdstringUUID of the contact created for this call
statusstringInitial call status: calling or failed
messagestringHuman-readable description of the dispatched status

​
Call Status Object

FieldTypeDescription
outboundCallIdstringUUID of the outbound call
contactIdstringUUID of the associated contact
statusstringCurrent status: calling, completed, failed, busy, or no-answer
callDetailsobjectPresent only when the call has reached a terminal state — contains timing and reason

​
Call Status Values

StatusDescription
callingThe call has been dispatched and is in progress
completedThe call connected and ended normally
failedThe call could not be completed due to an error
busyThe destination number was busy
no-answerThe call rang but was not answered

​
callDetails Object (terminal states only)

FieldTypeDescription
startedAtstringISO 8601 timestamp when the call started
endedAtstringISO 8601 timestamp when the call ended
durationintegerCall duration in seconds
endedReasonstringReason the call ended (e.g., customer-ended-call)

​
Using Dynamic Variables

Dynamic variables allow you to pass contextual information to the AI assistant at call time. The assistant can use these values to personalize the conversation — for example, addressing the patient by name or referencing a specific appointment. 
{
  "dynamicVariables": {
    "patientId": "12345",
    "appointmentSlot": "2026-04-01T10:00:00Z",
    "practitioner": "Dr. Smith"
  }
}
The keys available depend on how your AI assistant is configured in AlloMia.

​
Webhook Callback

When you provide a callbackUrl, AlloMia sends a POST request to that URL when the call reaches a terminal state. The payload mirrors the response from Get Outbound Call Status: 
{
  "outboundCallId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "contactId": "d4e5f6a7-b8c9-0123-defa-456789012345",
  "status": "completed",
  "callDetails": {
    "startedAt": "2026-04-01T14:30:00Z",
    "endedAt": "2026-04-01T14:32:30Z",
    "duration": 150,
    "endedReason": "customer-ended-call"
  }
}