Skip to main content

​
Welcome to the TopCalls API

The TopCalls API is a RESTful API that lets you build AI-powered phone agents. Make calls, manage phone numbers, check available models and voices, and integrate with your systems via webhooks.

RESTful Design

Standard HTTP methods and JSON responses. Works with any programming language.

Interactive

Try API endpoints directly in this documentation. See responses in real-time.

Webhooks

Real-time notifications for call events, tool calls, and campaign updates.

Well Documented

Detailed schemas, examples, and error responses for every endpoint.

​
Base URL

All API requests should be made to: 
https://api.topcalls.ai

​
Authentication

All API requests require authentication. Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
Get your API key from topcalls.ai. Sign in and create a new key in your account settings.

​
API Versioning

The current API version is v1. All endpoints are prefixed with /v1: 
https://api.topcalls.ai/v1/calls

​
Response Format

All responses are JSON. Success responses include the requested data: 
{
  "call_id": "564d4fd4-03bc-400a-abe0-05540fbeff88",
  "status": "queued"
}
Error responses follow RFC 7807 Problem+JSON format: 
{
  "status": 400,
  "title": "Invalid request body",
  "detail": "Phone number must be in E.164 format",
  "errors": [
    {
      "path": "phone_number",
      "message": "Phone number must be in E.164 format (e.g., +14155551234)"
    }
  ]
}

​
Quick Start

​
1. Make Your First Call

curl -X POST https://api.topcalls.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "task": "Call to confirm appointment...",
    "voice": "alloy"
  }'

​
2. Check Call Status

curl https://api.topcalls.ai/v1/calls/CALL_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

​
3. List Calls

curl https://api.topcalls.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY"

​
API Endpoints

​
Calls

MethodEndpointDescription
GET/v1/callsList calls
GET/v1/calls/{call_id}Get call details
POST/v1/callsCreate a new call
POST/v1/calls/{call_id}/stopStop an active call
POST/v1/calls/{call_id}/cancelCancel a queued call

​
Campaigns

Campaigns are created and configured through the TopCalls dashboard. The API provides monitoring and control:
MethodEndpointDescription
GET/v1/campaignsList campaigns
GET/v1/campaigns/{campaign_id}Get campaign details and stats
POST/v1/campaigns/{campaign_id}/startStart a campaign
POST/v1/campaigns/{campaign_id}/pausePause a running campaign

​
Phone Numbers

MethodEndpointDescription
GET/v1/phone-numbers/carriersList carriers
GET/v1/phone-numbersList phone numbers
GET/v1/phone-numbers/{phone_number_id}Get phone number details
POST/v1/phone-numbers/carriersAdd custom carrier (BYOC)
POST/v1/phone-numbersAdd phone number
DELETE/v1/phone-numbers/carriers/{carrier_id}Delete custom carrier
DELETE/v1/phone-numbers/{phone_number_id}Delete phone number

​
Configuration

MethodEndpointDescription
GET/v1/modelsList available AI models
GET/v1/voices/builtinList built-in voices (with filters)
GET/v1/voicesList voices for your account (including custom/cloned)

​
Account

MethodEndpointDescription
GET/v1/balanceGet account balance and usage

​
Webhooks

TopCalls sends webhooks to your server when events occur. Configure webhooks when creating calls: 
{
  "webhook_url": "https://your-app.com/webhooks/call-complete",
  "webhook_events": ["call.completed", "call.failed"]
}
See the Webhooks Guide for complete documentation.

​
Error Codes

Status CodeDescription
200Success
201Created
400Bad Request - Invalid input
401Unauthorized - Invalid or missing API key
402Payment Required - Insufficient quota
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests
500Internal Server Error

​
SDKs & Libraries

Official SDKs coming soon. For now, use any HTTP client library:
  • JavaScript/TypeScript: fetch, axios
  • Python: requests
  • Ruby: httparty
  • Go: net/http
  • PHP: guzzle

​
Support

​
Next Steps

Quickstart

Make your first call in 5 minutes.

Making Calls Guide

Learn how to make calls with the API.