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

# Outbound Calls API

> API endpoints for triggering and monitoring outbound AI-powered calls

# 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

<CardGroup cols={2}>
  <Card title="Create Outbound Call" icon="phone-arrow-up-right" href="/api-reference/endpoint/create-outbound-call">
    Trigger an immediate outbound call to a phone number using a specified AI assistant
  </Card>

  <Card title="Get Outbound Call Status" icon="circle-info" href="/api-reference/endpoint/get-outbound-call-status">
    Retrieve the current status and details of a previously created outbound call
  </Card>
</CardGroup>

## 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](/api-reference/authentication).

## 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

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

```json theme={null}
{
  "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](/api-reference/endpoint/get-outbound-call-status):

```json theme={null}
{
  "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"
  }
}
```