# TopCalls Voice API

> AI-powered calling, fully managed. Replace manual dialing. Scale without hiring. First calls live in 2 weeks.

## Docs

- [TopCalls Voice API](https://docs.topcalls.ai/index.md): AI-powered calling, fully managed. Replace manual dialing. Scale without hiring. First calls live in 2 weeks.
- [Quickstart](https://docs.topcalls.ai/quickstart.md): Make your first AI phone call in under 5 minutes.
- [How TopCalls Works](https://docs.topcalls.ai/concepts/overview.md): Understanding the architecture and capabilities of the TopCalls platform.
- [AI & Voice Customization](https://docs.topcalls.ai/concepts/ai-voice.md): Control how your agent sounds, behaves, and responds. Create the perfect AI persona for your use case.
- [Campaign Management](https://docs.topcalls.ai/concepts/campaigns.md): Queue management for automated outbound calls. Handle thousands of contacts with timezone awareness, retry logic, and real-time monitoring.
- [Crew (Multi-Agent Handoffs)](https://docs.topcalls.ai/concepts/crew.md): Run a call with multiple specialised agents that hand off to each other under controlled conditions.
- [Webhooks & Events](https://docs.topcalls.ai/concepts/webhooks.md): Receive notifications when calls finish. Understand the event model, delivery timing, and retry behavior.
- [Account Lifecycle](https://docs.topcalls.ai/concepts/account-lifecycle.md): What happens when you close your TopCalls account: immediate effects, the review period, reactivation, and permanent deletion.
- [Making Calls](https://docs.topcalls.ai/guides/making-calls.md): Learn how to make AI phone calls via the TopCalls API. From simple reminders to complex conversations with function calling.
- [Voice Library & Cloning](https://docs.topcalls.ai/guides/custom-voices.md): Choose from hundreds of built-in voices or clone your own. Create brand-consistent AI agents that sound exactly how you want.
- [Function Calling & Tools](https://docs.topcalls.ai/guides/function-calling.md): Give your AI agents tools to act during calls. Book appointments, update your CRM, send confirmations, and end calls gracefully.
- [Knowledge Bases](https://docs.topcalls.ai/guides/knowledge-bases.md): Give your AI agents the product, pricing, and policy knowledge they need to answer questions accurately during calls.
- [Crews](https://docs.topcalls.ai/guides/crews.md): Split one campaign across a small team of focused AI agents that pass the live call to each other.
- [Webhooks](https://docs.topcalls.ai/guides/webhooks.md): Receive notifications when calls finish. Deliver transcripts, recordings, and analysis straight to your systems.
- [Appointment Management](https://docs.topcalls.ai/use-cases/appointment-reminders.md): Automate appointment confirmations, rescheduling, and reminders with AI-powered phone calls.
- [Lead Qualification & Follow-ups](https://docs.topcalls.ai/use-cases/sales-outreach.md): Qualify inbound and warm leads with AI agents that schedule follow-ups and route qualified prospects to your sales team. For consented contacts only.
- [Customer Support](https://docs.topcalls.ai/use-cases/customer-support.md): Handle common support inquiries around the clock with AI agents. Escalate complex issues to human agents when needed.
- [Compliance & Collections](https://docs.topcalls.ai/use-cases/debt-collection.md): Professional, compliant collection calls with payment plan negotiation and full audit trails. Built-in compliance tooling.
- [Integrations](https://docs.topcalls.ai/integrations.md): Connect Topcalls to your tools to automate the call lifecycle. No code required.
- [API Reference](https://docs.topcalls.ai/api-reference/introduction.md): Complete REST API documentation for TopCalls. Build AI phone agents with our API.
- [List calls](https://docs.topcalls.ai/api-reference/calls/list-calls.md): Retrieve a paginated list of calls for your account.
- [Get call details](https://docs.topcalls.ai/api-reference/calls/get-call-details.md): Retrieve detailed information about a specific call
- [Create a new call](https://docs.topcalls.ai/api-reference/calls/create-a-new-call.md): Create and dispatch an AI-powered phone call. The call will be queued and executed immediately.
- [Stop an in-progress call](https://docs.topcalls.ai/api-reference/calls/stop-an-in-progress-call.md): Cancel or stop a call that is currently queued or in progress
- [Cancel a queued call](https://docs.topcalls.ai/api-reference/calls/cancel-a-queued-call.md): Cancel a call that hasn't started yet
- [List carriers](https://docs.topcalls.ai/api-reference/phone-numbers/list-carriers.md): Get all custom carriers (BYOC) you've added to your account.
- [List phone numbers](https://docs.topcalls.ai/api-reference/phone-numbers/list-phone-numbers.md): Get all phone numbers on your account.
- [Get phone number details](https://docs.topcalls.ai/api-reference/phone-numbers/get-phone-number-details.md): Retrieve detailed information about a specific phone number.
- [Add custom carrier](https://docs.topcalls.ai/api-reference/phone-numbers/add-custom-carrier.md): Add a custom SIP carrier (Bring Your Own Carrier).
- [Add phone number](https://docs.topcalls.ai/api-reference/phone-numbers/add-phone-number.md): Add a phone number to your account. The number is provisioned in the telephony system.
- [Update phone number](https://docs.topcalls.ai/api-reference/phone-numbers/update-phone-number.md): Partially update a phone number's `label` and/or `status`. At least one field is required. `status` only accepts `active` or `inactive`; a number that is currently `failed` or `pending` cannot have its status changed manually.
- [Delete custom carrier](https://docs.topcalls.ai/api-reference/phone-numbers/delete-custom-carrier.md): Delete a custom carrier. Cannot delete the TopCalls default carrier.
- [Delete phone number](https://docs.topcalls.ai/api-reference/phone-numbers/delete-phone-number.md): Remove a phone number from your account. The number is deprovisioned from the telephony system.
- [List lead lists](https://docs.topcalls.ai/api-reference/list-lead-lists.md): Returns all lead lists for the account, sorted by name. Requires scope: `leads:read`.
- [Create lead list](https://docs.topcalls.ai/api-reference/create-lead-list.md): Creates a lead list, or returns the existing row matching `(account_id, lower(trim(name)))`. Returns 201 on create, 200 on idempotent re-call. Requires scope: `leads:write`.
- [Get lead list details](https://docs.topcalls.ai/api-reference/get-lead-list-details.md): Returns a single lead list with its cached counters plus `fresh_counts` computed live from lead status. Requires scope: `leads:read`.
- [Update lead list](https://docs.topcalls.ai/api-reference/update-lead-list.md): Partially update `name` and/or `description`. At least one field is required. Requires scope: `leads:write`.
- [Create or attach lead](https://docs.topcalls.ai/api-reference/create-or-attach-lead.md): Creates a single lead and assigns it to the given list. Idempotent on `(account_id, phone_number)`: if a lead with this phone number already exists in the account, the existing lead is attached to the requested list (no error) and the response carries `existed: true` with HTTP 200. A genuinely new l…
- [List leads](https://docs.topcalls.ai/api-reference/list-leads.md): Cursor-paginated list of leads. Requires scope: `leads:read`.
- [Get lead by id](https://docs.topcalls.ai/api-reference/get-lead-by-id.md): Requires scope: `leads:read`.
- [Update lead](https://docs.topcalls.ai/api-reference/update-lead.md): Requires scope: `leads:write`. Body must contain at least one field; `notes` and `notes_append` are mutually exclusive.
- [Delete lead](https://docs.topcalls.ai/api-reference/delete-lead.md): Without `list_id`, hard-deletes the lead row (assignments cascade). With `list_id`, removes only that assignment; if no assignments remain, the lead row is also deleted. Requires scope: `leads:write`.
- [Bulk import leads](https://docs.topcalls.ai/api-reference/bulk-import-leads.md): Imports up to 2000 leads in a single transaction. `mode='merge'` (default) timestamp-appends notes and DISTINCT-unions tags on existing rows; `mode='skip'` leaves existing rows untouched. Requires scope: `leads:write`.
- [Bulk delete leads (hybrid sync/async)](https://docs.topcalls.ai/api-reference/bulk-delete-leads-hybrid-syncasync.md): Delete leads in bulk. Polymorphic body: pass `ids: uuid[]` (max 500, sync only) OR `filter: {list_id?, status?, tag?}` (any size; gateway recounts then auto-routes sync if <=500 / async via job table if >500).
- [Poll a bulk-delete job](https://docs.topcalls.ai/api-reference/poll-a-bulk-delete-job.md): Returns the current status of an async bulk-delete job created by the 202 branch of `POST /v1/leads/bulk-delete`. Poll until `status` is a terminal value (`completed`, `completed_with_skipped`, `failed`, or `canceled`). Requires scope: `leads:read`.
- [List campaigns](https://docs.topcalls.ai/api-reference/campaigns/list-campaigns.md): List campaigns for your account, ordered by creation time (newest first).
- [Create a campaign](https://docs.topcalls.ai/api-reference/campaigns/create-a-campaign.md): Create a campaign. It is always created with status `draft`; use `POST /v1/campaigns/{id}/start` to launch it. Optionally attach lead lists at creation time via `lead_list_ids`; one `campaign_lead_lists` row is created per id.
- [Get campaign details](https://docs.topcalls.ai/api-reference/campaigns/get-campaign-details.md): Retrieve a single campaign by id, scoped to the authenticated account.
- [Update a campaign](https://docs.topcalls.ai/api-reference/campaigns/update-a-campaign.md): Partially update a campaign. Every field is optional; only the fields you send are changed. `status` can never be set here. Use the lifecycle endpoints (start/pause/resume/stop) to change it.
- [Get campaign statistics](https://docs.topcalls.ai/api-reference/campaigns/get-campaign-statistics.md): Returns call counters for the campaign, computed from call records at request time, plus the current (most recently created) run, if one exists. `stats` is all zero when the campaign has no calls yet. `current_run` is `null` when the campaign has never been started.
- [Start a campaign](https://docs.topcalls.ai/api-reference/campaigns/start-a-campaign.md): Validates the campaign (lead lists attached, leads present, account quota covers a call's dial-time reserve), creates a campaign run, and marks the campaign `running` so workers begin queuing calls. If the campaign has a future `schedule_time`, validation runs the same way but the campaign is moved…
- [Pause a campaign](https://docs.topcalls.ai/api-reference/campaigns/pause-a-campaign.md): Marks the campaign run `paused` and the campaign `paused` so the producer stops queuing new calls; in-flight calls are unaffected. The response returns as soon as the status flips. Cleanup of already-queued calls (so a later resume starts from fresh lead data) runs asynchronously afterward and is no…
- [Resume a paused campaign](https://docs.topcalls.ai/api-reference/campaigns/resume-a-paused-campaign.md): Resumes the campaign's paused run (account quota is re-checked, the same way as start) and marks the campaign `running` again. Queued calls were removed on pause, so the producer creates new calls with the campaign's current configuration and lead data.
- [Stop a campaign](https://docs.topcalls.ai/api-reference/campaigns/stop-a-campaign.md): Permanently stops the campaign: marks its run `stopped` and the campaign `completed`, then cancels queued calls in place (they stay in call history, marked cancelled, rather than being deleted). A stopped campaign cannot be resumed. Start a new one instead.
- [Place a test call for a campaign](https://docs.topcalls.ai/api-reference/campaigns/place-a-test-call-for-a-campaign.md): Dials the given phone number using the campaign's current configuration, without linking the call to any lead or campaign run. This is a real outbound call: it reserves account minutes the same way any other call does and is billed on completion like any other call. Use it to verify a campaign's scr…
- [List knowledge base entries](https://docs.topcalls.ai/api-reference/list-knowledge-base-entries.md): Returns the account's knowledge base text entries, newest first. Requires scope: `knowledge_base:read`.
- [Get knowledge base entry](https://docs.topcalls.ai/api-reference/get-knowledge-base-entry.md): Returns a single knowledge base entry owned by the account. Requires scope: `knowledge_base:read`.
- [Create knowledge base entry](https://docs.topcalls.ai/api-reference/create-knowledge-base-entry.md): Creates one knowledge base text entry. `description_category` defaults to `company_information` when omitted, so a minimal `{ name, content }` body succeeds; a `custom` category requires a non-empty `custom_description`. Entry names are unique within the account. Requires scope: `knowledge_base:writ…
- [Update knowledge base entry](https://docs.topcalls.ai/api-reference/update-knowledge-base-entry.md): Partially update an owned entry. At least one field is required. When the category is set to `custom`, `custom_description` must be provided. Requires scope: `knowledge_base:write`.
- [Delete knowledge base entry](https://docs.topcalls.ai/api-reference/delete-knowledge-base-entry.md): Hard-deletes an owned entry; any campaign attachments are removed automatically. Requires scope: `knowledge_base:write`.
- [List webhook subscriptions](https://docs.topcalls.ai/api-reference/webhooks/list-webhook-subscriptions.md): List active webhook subscriptions for the authenticated account. Soft-deleted rows are excluded.
- [Create a webhook subscription](https://docs.topcalls.ai/api-reference/webhooks/create-a-webhook-subscription.md): Subscribe a URL to receive events from your account. v1 supports `call.completed` and disposition-suffixed variants like `call.completed.booked_callback`. The `lead.status_changed` and `campaign.activated` / `campaign.paused` event names are reserved for future use.
- [Get a webhook subscription](https://docs.topcalls.ai/api-reference/webhooks/get-a-webhook-subscription.md): Retrieve a single webhook subscription by id, scoped to the authenticated account. Returns 404 for unknown ids, rows belonging to a different account, or soft-deleted rows.
- [Update a webhook subscription](https://docs.topcalls.ai/api-reference/webhooks/update-a-webhook-subscription.md): Partially update a webhook subscription's `event`, `url`, and/or `filters`. At least one field is required. Values go through the same validation as `POST /v1/webhooks`. Returns 404 for unknown ids, rows belonging to a different account, or soft-deleted rows.
- [Delete a webhook subscription](https://docs.topcalls.ai/api-reference/webhooks/delete-a-webhook-subscription.md): Soft-delete the subscription (sets `deleted_at`). Idempotent - deleting a row that's already soft-deleted also returns 204. Returns 404 for unknown ids or rows belonging to a different account.
- [List available models](https://docs.topcalls.ai/api-reference/configuration/list-available-models.md): Returns all available AI models grouped by mode.
- [List built-in voices](https://docs.topcalls.ai/api-reference/configuration/list-built-in-voices.md): Returns built-in voices grouped by mode and provider. These voices are available without any additional setup.
- [List voices](https://docs.topcalls.ai/api-reference/configuration/list-voices.md): Returns available voices for your account, including system voices and any custom/cloned voices.
- [Get account balance](https://docs.topcalls.ai/api-reference/account/get-account-balance.md): Get your account's remaining call minutes and usage information
- [List usage ledger movements](https://docs.topcalls.ai/api-reference/account/list-usage-ledger-movements.md): Cursor-paginated raw ledger of minute-consumption events. Each row records the minutes consumed by a single source (e.g. a call) at the time it happened. This is a raw-column surface: field names mirror the ledger schema rather than the derived balance shown by `GET /v1/balance`.
- [Daily call analytics](https://docs.topcalls.ai/api-reference/account/daily-call-analytics.md): Returns pre-aggregated daily call counters for the given date range, ordered by day ascending. `start_date` and `end_date` are both required and the window must not exceed 90 days.

## OpenAPI Specs

- [openapi](https://docs.topcalls.ai/api-reference/openapi.json)

## Optional

- [Website](https://topcalls.ai)