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

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.
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).
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

Field	Type	Required	Description
phoneNumber	string	Yes	Phone number to call in E.164 format (e.g. `+15145551234`)
assistantId	string	Yes	UUID of the AI assistant to use for the call
phoneNumberId	string	Yes	UUID of the AlloMia phone number to call from
customerName	string	No	Name of the person being called
dynamicVariables	object	No	Key-value pairs passed as dynamic variables to the AI assistant at call time
callbackUrl	string	No	URL to receive a `POST` webhook when the call reaches a terminal state

Outbound Call Response

Field	Type	Description
outboundCallId	string	UUID identifying this outbound call record
contactId	string	UUID of the contact created for this call
status	string	Initial call status: `calling` or `failed`
message	string	Human-readable description of the dispatched status

Call Status Object

Field	Type	Description
outboundCallId	string	UUID of the outbound call
contactId	string	UUID of the associated contact
status	string	Current status: `calling`, `completed`, `failed`, `busy`, or `no-answer`
callDetails	object	Present only when the call has reached a terminal state — contains timing and reason

Call Status Values

Status	Description
`calling`	The call has been dispatched and is in progress
`completed`	The call connected and ended normally
`failed`	The call could not be completed due to an error
`busy`	The destination number was busy
`no-answer`	The call rang but was not answered

`callDetails` Object (terminal states only)

Field	Type	Description
startedAt	string	ISO 8601 timestamp when the call started
endedAt	string	ISO 8601 timestamp when the call ended
duration	integer	Call duration in seconds
endedReason	string	Reason 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"
  }
}

API Documentation

Organizations (Tenant Only)

Calls

Outbound Calls

Outbound Calls API

Overview

Available Endpoints

Create Outbound Call

Get Outbound Call Status

Authentication

How It Works

Data Structures

Outbound Call Request

Outbound Call Response

Call Status Object

Call Status Values

`callDetails` Object (terminal states only)

Using Dynamic Variables

Webhook Callback

​Overview

​Available Endpoints

Create Outbound Call

Get Outbound Call Status

​Authentication

​How It Works

​Data Structures

​Outbound Call Request

​Outbound Call Response

​Call Status Object

​Call Status Values

​callDetails Object (terminal states only)

​Using Dynamic Variables

​Webhook Callback

Overview

Available Endpoints

Authentication

How It Works

Data Structures

Outbound Call Request

Outbound Call Response

Call Status Object

Call Status Values

`callDetails` Object (terminal states only)

Using Dynamic Variables

Webhook Callback