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
- A connector configured for outbound calls
- API authentication token (X-PolyAi-Auth-Token)
Contact your PolyAI representative to enable outbound calling for your project and obtain the necessary credentials.
Base URL
Use the regional endpoint that matches your deployment:
| 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 |
Authentication
All outbound calling endpoints require authentication using the X-PolyAi-Auth-Token header:
curl -X POST https://api.{region}.platform.polyai.app/outbound/trigger \
-H "X-PolyAi-Auth-Token: YOUR_CONNECTOR_TOKEN" \
-H "Content-Type: application/json"
Call flow
- Trigger call - POST to
/outbound/trigger with phone number and metadata
- Receive call SID - API returns a unique call identifier
- Check status - GET
/outbound/status/{call_sid} to monitor call progress
- Handle completion - Call status updates to
completed, failed, or no-answer
Call statuses
| Status | Description |
|---|
queued | Call has been queued for processing |
ringing | Call is ringing at the destination |
in-progress | Call is active and connected |
completed | Call ended successfully |
failed | Call failed to connect |
no-answer | Call was not answered |
busy | Destination was busy |
cancelled | Call was cancelled before connection |
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 - Poll the status endpoint to track call progress
- Use metadata - Pass context in the metadata field to personalize conversations
- Respect time zones - Schedule calls during appropriate hours for the destination region
