The Outbound Calling API allows you to programmatically initiate outbound calls and check their status. This is useful 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)
Contact your PolyAI representative to enable outbound calling for your project and obtain the necessary credentials.
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:
curl -X POST https://api.{region}.platform.polyai.app/v1/outbound-calling/trigger \
-H "X-PolyAi-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json"
Call flow
- Trigger call - POST to
/v1/outbound-calling/trigger with the destination phone number
- Receive call SID - API returns a unique call identifier (
callSid)
- Check status - GET
/v1/outbound-calling/{callSid}/status to monitor call progress
- 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
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.
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
