> ## 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 an immediate outbound call to a phone number using the specified AI assistant

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

<ParamField header="Authorization" type="string" required>
  API key is required. Enter either your tenant-specific or organization-specific API key in the format `Bearer YOUR-API-KEY`
</ParamField>

### Body Parameters

<ParamField body="phoneNumber" type="string" required>
  Phone number to call. E.164 format is recommended (e.g. `+15145551234`). Must be between 10 and 20 characters.
</ParamField>

<ParamField body="assistantId" type="string" required>
  UUID of the AI assistant to use for the call. The assistant must belong to the organization associated with the API key.
</ParamField>

<ParamField body="phoneNumberId" type="string" required>
  UUID of the AlloMia phone number to call from. The phone number must belong to the organization associated with the API key.
</ParamField>

<ParamField body="customerName" type="string">
  Name of the person being called. When provided, the AI assistant can use this to personalize the conversation.
</ParamField>

<ParamField body="dynamicVariables" type="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).

  ```json theme={null}
  {
    "patientId": "12345",
    "appointmentSlot": "2026-04-01T10:00:00Z",
    "practitioner": "Dr. Smith"
  }
  ```
</ParamField>

<ParamField body="callbackUrl" type="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](/api-reference/endpoint/get-outbound-call-status) response.
</ParamField>

### Response

<ResponseField name="outboundCallId" type="string">
  UUID uniquely identifying this outbound call record. Use this ID to poll [Get Outbound Call Status](/api-reference/endpoint/get-outbound-call-status) and track the call's progress.
</ResponseField>

<ResponseField name="contactId" type="string">
  UUID of the contact record created for this outbound call.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status of the call. Always `calling` on success, indicating the call has been dispatched.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable description of the dispatched status (e.g., `"Outbound call dispatched"`).
</ResponseField>

### Example Request

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

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

### Error Responses

<AccordionGroup>
  <Accordion title="400: Invalid request data">
    Returned when the request body fails validation. The `details` array lists each field-level error.

    ```json theme={null}
    {
      "error": "Invalid request data",
      "details": [
        {
          "field": "phoneNumber",
          "message": "Phone number must be at least 10 digits",
          "code": "too_small"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="401: Unauthorized">
    Returned when the API key is missing or invalid.

    ```json theme={null}
    {
      "error": "Invalid or missing API key"
    }
    ```
  </Accordion>

  <Accordion title="403: Forbidden">
    Returned when the API key does not have the required permissions to trigger outbound calls.

    ```json theme={null}
    {
      "error": "Insufficient permissions"
    }
    ```
  </Accordion>

  <Accordion title="404: Resource not found">
    Returned when the specified assistant or phone number does not exist or does not belong to the organization.

    ```json theme={null}
    {
      "error": "Assistant or phone number not found"
    }
    ```
  </Accordion>

  <Accordion title="422: Organization inactive">
    Returned when the organization associated with the API key is inactive.

    ```json theme={null}
    {
      "error": "Organization is inactive"
    }
    ```
  </Accordion>

  <Accordion title="500: Internal server error">
    ```json theme={null}
    {
      "error": "Internal server error occurred"
    }
    ```
  </Accordion>
</AccordionGroup>