API Reference - TopCalls Voice API

Welcome to the TopCalls API

A REST API for AI phone agents. Place calls, run campaigns, manage leads and phone numbers, and get each call’s result by webhook.

RESTful Design

Standard HTTP methods and JSON. Works from any language.

Interactive

Send requests from these pages and see the live response.

Webhooks

A notification when each call finishes, with its transcript, summary and outcome.

Well Documented

Schemas, examples and error responses for every endpoint.

Base URL

https://api.topcalls.ai

Authentication

Every request needs your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Each key carries scopes, one per group of endpoints. Grant only what the key needs. A request outside the key’s scopes returns 403, and detail names the missing scope. New keys don’t include calls:write, campaigns:write or the leads scopes unless you tick them.

Scope	Grants access to
`calls:read`	List and read calls (details, transcripts, recordings), plus remaining credit, usage history, and call analytics
`calls:write`	Create, stop, and cancel calls
`campaigns:read`	List campaigns and read campaign details and stats
`campaigns:write`	Create, update, start, pause, resume, stop, and test campaigns
`phone_numbers:read`	List phone numbers and carriers, and read phone number details
`phone_numbers:write`	Add and remove phone numbers, manage custom carriers (BYOC), and attach inbound routing
`leads:read`	List and read leads and lead lists
`leads:write`	Create, update, delete, and bulk-import leads, and create and update lead lists
`knowledge_base:read`	List and read knowledge base entries
`knowledge_base:write`	Create, update, and delete knowledge base entries
`webhooks:read`	List and read webhook subscriptions
`webhooks:write`	Create, update, and delete webhook subscriptions

A read scope never grants writes. The catalog endpoints (/v1/models, /v1/voices, /v1/voices/builtin) need no scope.

API Versioning

The current version is v1, and every path starts with /v1:

https://api.topcalls.ai/v1/calls

Response Format

Responses are JSON. Creating a call returns:

{
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "provider_call_id": "64e9bf0e-7c2f-4443-a759-7eb1731cd583",
  "status": "queued"
}

Errors use RFC 7807 Problem+JSON. A validation error lists each bad field:

{
  "status": 400,
  "title": "Invalid request body",
  "errors": [
    {
      "path": "phone_number",
      "message": "Phone number must be in E.164 format (e.g., +14155551234)",
      "code": "invalid_string"
    }
  ]
}

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..."
  }'

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

Method	Endpoint	Description
`GET`	`/v1/calls`	List calls
`GET`	`/v1/calls/{call_id}`	Get call details
`POST`	`/v1/calls`	Create a new call
`POST`	`/v1/calls/{call_id}/stop`	Stop a queued or in-progress call
`POST`	`/v1/calls/{call_id}/cancel`	Cancel a queued or in-progress call

Campaigns

Method	Endpoint	Description
`POST`	`/v1/campaigns`	Create a campaign
`GET`	`/v1/campaigns`	List campaigns
`GET`	`/v1/campaigns/{campaign_id}`	Get campaign details
`GET`	`/v1/campaigns/{campaign_id}/stats`	Get campaign stats
`PATCH`	`/v1/campaigns/{campaign_id}`	Update a campaign
`POST`	`/v1/campaigns/{campaign_id}/start`	Start a campaign
`POST`	`/v1/campaigns/{campaign_id}/pause`	Pause a running campaign
`POST`	`/v1/campaigns/{campaign_id}/resume`	Resume a paused campaign
`POST`	`/v1/campaigns/{campaign_id}/stop`	Stop a campaign
`POST`	`/v1/campaigns/{campaign_id}/test`	Place a test call for a campaign

Phone Numbers

Method	Endpoint	Description
`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
`PATCH`	`/v1/phone-numbers/{phone_number_id}`	Update phone number label/status
`DELETE`	`/v1/phone-numbers/carriers/{carrier_id}`	Delete custom carrier
`DELETE`	`/v1/phone-numbers/{phone_number_id}`	Delete phone number

Leads

Method	Endpoint	Description
`POST`	`/v1/leads`	Create a lead (idempotent per phone number)
`GET`	`/v1/leads`	List leads with cursor pagination and filters
`GET`	`/v1/leads/{id}`	Get lead details
`PATCH`	`/v1/leads/{id}`	Update a lead
`DELETE`	`/v1/leads/{id}`	Delete a lead
`POST`	`/v1/leads/bulk`	Bulk import leads
`POST`	`/v1/leads/bulk-delete`	Bulk delete leads
`GET`	`/v1/leads/bulk-delete/{job_id}`	Poll an async bulk-delete job

Lead Lists

Method	Endpoint	Description
`GET`	`/v1/lead-lists`	List lead lists
`GET`	`/v1/lead-lists/{lead_list_id}`	Get lead list details
`POST`	`/v1/lead-lists`	Create a lead list
`PATCH`	`/v1/lead-lists/{lead_list_id}`	Update a lead list

Knowledge Bases

Method	Endpoint	Description
`GET`	`/v1/knowledge-bases`	List knowledge base entries
`GET`	`/v1/knowledge-bases/{id}`	Get a knowledge base entry
`POST`	`/v1/knowledge-bases`	Create a knowledge base entry
`PATCH`	`/v1/knowledge-bases/{id}`	Update a knowledge base entry
`DELETE`	`/v1/knowledge-bases/{id}`	Delete a knowledge base entry

Webhooks

Method	Endpoint	Description
`POST`	`/v1/webhooks`	Create a webhook subscription
`GET`	`/v1/webhooks`	List webhook subscriptions
`GET`	`/v1/webhooks/{webhook_id}`	Get a webhook subscription
`PATCH`	`/v1/webhooks/{webhook_id}`	Update a webhook subscription
`DELETE`	`/v1/webhooks/{webhook_id}`	Delete a webhook subscription

Configuration

Method	Endpoint	Description
`GET`	`/v1/models`	List available AI models
`GET`	`/v1/voices/builtin`	List built-in voices (with filters)
`GET`	`/v1/voices`	List the built-in Legacy voices as a flat list

Account

Method	Endpoint	Description
`GET`	`/v1/balance`	Get prepaid credit, rate, concurrency, and auto-recharge
`GET`	`/v1/usage/movements`	List credit ledger entries
`GET`	`/v1/analytics/calls`	Daily call analytics

Webhooks

TopCalls posts to your server when a call finishes. Set webhook_url on a call for per-call delivery:

{
  "webhook_url": "https://your-app.com/webhooks/call-complete"
}

Or subscribe the whole account with POST /v1/webhooks, including disposition events such as call.completed.booked_callback. Details are in the Webhooks Guide.

Idempotency

These endpoints accept an optional Idempotency-Key header (8 to 255 characters from [A-Za-z0-9_-]): call create, stop and cancel; campaign create, update, start, pause, resume, stop and test; knowledge base create and update; phone number and carrier create; webhook subscription create and update. Other endpoints ignore it. Only a 2xx response is stored, for 24 hours, and a retry with the same key gets it back with the header Idempotent-Replay: true. Errors aren’t stored, so a retry after one runs again. The body isn’t compared: reuse a key with a different body and you still get the first response. A key reused while the first request is still running gets 409, and a malformed key gets 400.

Rate Limits

Three limits apply, all per account and shared by every key on it:

All endpoints: 120 requests per minute unless your account was raised. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Over it you get 429 with Retry-After and a plain-text body, not Problem+JSON.
POST /v1/calls: your account’s max_calls_per_minute (default 20) over a fixed 60-second window. Going over returns 429 with Retry-After: 60 and code: RATE_LIMITED, shown below.
Concurrent calls: a call placed while every concurrent-call slot is in use gets 429 with code: concurrency_limit and no Retry-After. Place it again once a call in progress ends.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/problem+json

{
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Your account has reached its per-minute call rate limit (max_calls_per_minute). Wait for the number of seconds in the Retry-After header, then retry.",
  "code": "RATE_LIMITED"
}

On a 429 with Retry-After, wait that many seconds and send the same request again. If it keeps coming back, double the wait each time and slow down. Extra keys or servers on the same account don’t raise the ceiling. For steady volume, run a campaign instead of single POST /v1/calls requests, or contact us to raise a limit.

Error Codes

Status Code	Description
`200`	Success
`201`	Created
`202`	Accepted: a large bulk delete runs as a job you poll
`400`	Invalid input, or a malformed `Idempotency-Key`
`401`	Missing or invalid API key
`402`	Not enough credit to admit the call (`code: insufficient_quota`)
`403`	Forbidden, usually a missing scope
`404`	Not found
`409`	Conflict: a duplicate (lead, knowledge base entry name), a state that blocks the change, or an `Idempotency-Key` still in flight
`413`	Request body over 2 MB
`422`	Refused, and `code` says why: a prompt-safety code such as `PROMPT_SAFETY_FRAUD`, `CREW_CONFIG_INVALID`, `destination_not_allowed`, or `from_number_not_owned` (a `from_number` on a call or in a campaign `config` that isn’t an active or verified number on your account)
`429`	Rate or concurrency limit. See Rate Limits
`500`	Server error
`502`	The call failed to dial. It’s marked failed and its credit hold is released
`503`	A check the call depends on is briefly down (`destination_policy_unavailable`). No call is placed. Retry shortly

Destinations your account can call

Calls go to mobile, landline, VoIP and business numbers in the countries enabled for your account. Toll-free, pager, personal and high-cost numbers are refused, as are countries not enabled and numbers written with a trunk zero. A refusal returns 422 with code: destination_not_allowed, places no call and holds no credit. A scheduled call is checked when you create it and again when it comes due. To enable a country, contact support.

SDKs & Libraries

There’s no official SDK yet. Any HTTP client works: fetch or axios, Python requests, Go net/http, PHP guzzle.

Support

Documentation: guides and concepts
Contact: hello@topcalls.ai
Get Your Deployment Plan: book a free discovery call

Next Steps

Quickstart

Make your first call in 5 minutes.

Making Calls Guide

Learn how to make calls with the API.

​Welcome to the TopCalls API

RESTful Design

Interactive

Webhooks

Well Documented

​Base URL

​Authentication

​API Versioning

​Response Format

​Quick Start

​1. Make Your First Call

​2. Check Call Status

​3. List Calls

​API Endpoints

​Calls

​Campaigns

​Phone Numbers

​Leads

​Lead Lists

​Knowledge Bases

​Webhooks

​Configuration

​Account

​Webhooks

​Idempotency

​Rate Limits

​Error Codes

​Destinations your account can call

​SDKs & Libraries

​Support

​Next Steps

Quickstart

Making Calls Guide

Welcome to the TopCalls API

Base URL

Authentication

API Versioning

Response Format

Quick Start

1. Make Your First Call

2. Check Call Status

3. List Calls

API Endpoints

Calls

Campaigns

Phone Numbers

Leads

Lead Lists

Knowledge Bases

Webhooks

Configuration

Account

Webhooks

Idempotency

Rate Limits

Error Codes

Destinations your account can call

SDKs & Libraries

Support

Next Steps