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
- Your account ID and project ID
- Connector ID for authentication
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 |
Endpoint paths
All outbound calling endpoints include your account and project IDs in the path:
/api/v1/{account_id}/{project_id}/outbound-call/...
Authentication
All outbound calling endpoints require authentication using the X-CONNECTOR-ID header:
curl -X POST https://api.{region}.platform.polyai.app/api/v1/{account_id}/{project_id}/outbound-call/trigger \
-H "X-CONNECTOR-ID: YOUR_CONNECTOR_ID" \
-H "Content-Type: application/json"
Call flow
- Trigger call - POST to
/api/v1/{account_id}/{project_id}/outbound-call/trigger with phone number
- Receive conversation ID - API returns a unique call identifier (starts with
OUT-)
- Check status - GET
/api/v1/{account_id}/{project_id}/outbound-call/status/{call_sid} to monitor call progress
- Handle completion - Call status updates to
completed, failed, or no-answer
Call statuses
| Status | Description |
|---|
CREATED | Call record has been created |
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 |
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
