API Reference

Welcome to the TopCalls API

The TopCalls Voice API is a RESTful API that lets you build AI-powered phone agents. Make calls, manage campaigns, configure knowledge bases, and integrate with your systems.

RESTful Design

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

Comprehensive

Complete API coverage for calls, campaigns, knowledge bases, and more.

Interactive

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

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)"
    }
  ]
}

API Key Scopes

API keys can have different scopes to limit access:

Scope	Description
`calls:read`	Read call records and balance
`calls:write`	Create and cancel calls
`campaigns:read`	Read campaigns
`campaigns:write`	Create, update, control campaigns
`knowledge:read`	Read knowledge bases
`knowledge:write`	Create, update, delete knowledge bases
`phone_numbers:read`	Read phone numbers and carriers
`phone_numbers:write`	Add and remove phone numbers and carriers

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

GET /v1/calls - List calls
GET /v1/calls/{call_id} - Get call details
POST /v1/calls - Create a new call
DELETE /v1/calls/{call_id} - Cancel a call

Campaigns

GET /v1/campaigns - List campaigns
GET /v1/campaigns/{campaign_id} - Get campaign details
POST /v1/campaigns - Create a campaign
POST /v1/campaigns/{campaign_id}/start - Start campaign
POST /v1/campaigns/{campaign_id}/pause - Pause campaign
POST /v1/campaigns/{campaign_id}/resume - Resume campaign
POST /v1/campaigns/{campaign_id}/stop - Stop campaign
PATCH /v1/campaigns/{campaign_id} - Update campaign

Knowledge Bases

GET /v1/knowledge - List knowledge bases
GET /v1/knowledge/{kb_id} - Get knowledge base details
POST /v1/knowledge - Create knowledge base
PATCH /v1/knowledge/{kb_id} - Update knowledge base
DELETE /v1/knowledge/{kb_id} - Delete knowledge base

Phone Numbers

GET /v1/phone-numbers/carriers - List carriers
GET /v1/phone-numbers - List phone numbers
GET /v1/phone-numbers/{phone_number_id} - Get phone number details
POST /v1/phone-numbers/carriers - Add custom carrier (BYOC)
POST /v1/phone-numbers - Add phone number
DELETE /v1/phone-numbers/carriers/{carrier_id} - Delete custom carrier
DELETE /v1/phone-numbers/{phone_number_id} - Delete phone number

Configuration

GET /v1/models - List available AI models (LLM, STT, TTS)
GET /v1/voices/builtin - List built-in voices (with filters)
GET /v1/voices - List voices for your account (including custom/cloned)

Account

GET /v1/balance - Get account balance and usage

Webhooks

TopCalls sends webhooks to your server when events occur. Configure webhooks when creating calls or campaigns:

{
  "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 Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid input
`401`	Unauthorized - Invalid or missing API key
`402`	Payment Required - Insufficient quota
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests
`500`	Internal Server Error
`502`	Bad Gateway - Provider 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

Documentation: Browse our guides and concepts
Contact: Email us at hello@topcalls.ai
Get Your Deployment Plan: Book a discovery call for a free consultation and tailored proposal delivered within 48 hours

Overview

Calls

Phone Numbers

Configuration

Account

Welcome to the TopCalls API

RESTful Design

Comprehensive

Interactive

Well Documented

Base URL

Authentication

API Versioning

Response Format

API Key Scopes

Quick Start

1. Make Your First Call

2. Check Call Status

3. List Calls

API Endpoints

Calls

Campaigns

Knowledge Bases

Phone Numbers

Configuration

Account

Webhooks

Error Codes

SDKs & Libraries

Support

Next Steps

Quickstart

Making Calls Guide

Overview

Calls

Phone Numbers

Configuration

Account

​Welcome to the TopCalls API

RESTful Design

Comprehensive

Interactive

Well Documented

​Base URL

​Authentication

​API Versioning

​Response Format

​API Key Scopes

​Quick Start

​1. Make Your First Call

​2. Check Call Status

​3. List Calls

​API Endpoints

​Calls

​Campaigns

​Knowledge Bases

​Phone Numbers

​Configuration

​Account

​Webhooks

​Error Codes

​SDKs & Libraries

​Support

​Next Steps

Quickstart

Making Calls Guide

Welcome to the TopCalls API

Base URL

Authentication

API Versioning

Response Format

API Key Scopes

Quick Start

1. Make Your First Call

2. Check Call Status

3. List Calls

API Endpoints

Calls

Campaigns

Knowledge Bases

Phone Numbers

Configuration

Account

Webhooks

Error Codes

SDKs & Libraries

Support

Next Steps