Skip to main content
New integrations should use the Agents API’s outbound calls endpoints. Those endpoints are the official, supported way to trigger and monitor outbound calls for an agent going forward. The standalone Outbound Calling API documented on this page is the legacy endpoint — existing integrations continue to work, but new work should target the Agents API.
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:

​
Endpoint paths

Outbound calling endpoints use the following path structure:

​
Authentication

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

​
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 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 July 2, 2026