> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/api-reference/outbound/introduction",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Outbound Calling API

> Trigger outbound calls and monitor status for customer outreach, reminders, and notifications.

The Outbound Calling API lets you programmatically initiate outbound calls and monitor their status. Use it for proactive customer outreach, appointment reminders, and automated notifications.

## Prerequisites

* An active PolyAI project with outbound calling enabled
* An authentication token provided by your PolyAI representative
* Your base URL (provided per project by PolyAI)

<Note>Contact your PolyAI representative to enable outbound calling for your project and obtain the necessary credentials.</Note>

## Base URL

Your base URL is provided by PolyAI when outbound calling is configured for your project. Regional endpoints include:

| Region | Base URL                                |
| ------ | --------------------------------------- |
| US     | `https://api.us-1.platform.polyai.app`  |
| UK     | `https://api.uk-1.platform.polyai.app`  |
| EUW    | `https://api.euw-1.platform.polyai.app` |

## Endpoint paths

Outbound calling endpoints use the following path structure:

```
/{version}/outbound-calling/...
```

## Authentication

All outbound calling endpoints require authentication using the `X-PolyAi-Auth-Token` header:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.{region}.platform.polyai.app/v1/outbound-calling \
  -H "X-PolyAi-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json"
```

## Call flow

1. **Trigger call** - POST to `/v1/outbound-calling` with the destination phone number (and optional `metadata` and `encryption`)
2. **Receive call SID** - API returns a unique call identifier (`call_sid`, prefixed with `OUT-`)
3. **Check status** - GET `/v1/outbound-calling/{call_sid}/status` to monitor call progress
4. **Handle completion** - Call status updates to `success` or `failure`

## Call statuses

| Status    | Description                                |
| --------- | ------------------------------------------ |
| `queued`  | Call has been queued for processing        |
| `calling` | Call is being placed to the destination    |
| `success` | Call completed successfully                |
| `failure` | Call failed to connect or was not answered |

## Status data retention

<Warning>
  Call status data is retained for approximately **2 hours** after the call ends. After this period, the status endpoint will return a 404 Not Found error. If you need to retain call data longer, poll and store the status data before it expires.
</Warning>

## Rate limits

Outbound calling is subject to rate limits based on your account configuration. Contact your PolyAI representative to adjust limits for your use case.

## Best practices

* **Validate phone numbers** - Ensure numbers are in E.164 format before triggering calls
* **Handle failures gracefully** - Implement retry logic with exponential backoff
* **Monitor status promptly** - Poll the status endpoint within 2 hours of call completion
* **Store status data** - If you need call status beyond 2 hours, store it in your own system
* **Respect time zones** - Schedule calls during appropriate hours for the destination region