Skip to main content

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.

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)
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:
RegionBase URL
UShttps://api.us-1.platform.polyai.app
UKhttps://api.uk-1.platform.polyai.app
EUWhttps://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

  1. Trigger call - POST to /v1/outbound-calling/trigger with the destination phone number
  2. Receive call SID - API returns a unique call identifier (callSid)
  3. Check status - GET /v1/outbound-calling/{callSid}/status to monitor call progress
  4. Handle completion - Call status updates to success or failure

​
Call statuses

StatusDescription
queuedCall has been queued for processing
callingCall is being placed to the destination
successCall completed successfully
failureCall 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
Last modified on April 20, 2026