Create a voice Session: a short-lived, single-conversation reservation that lets a client hold a live voice chat with your agent. This is step 1 of 2. Creating the Session does not start any audio on its own; it returns a ws_url that a client then connects to over WebSocket to actually talk.

Call this endpoint from your server with your API key, and return only the ws_url to your client. The API key must never reach the browser. The ws_url is the only thing the client needs, and it is safe to hand out because it is single-use and expires. For how to connect and talk, see "Connect the client and talk" below the request details.

(Tags: Sessions)

Retrieve all agents for the authenticated user with pagination support. (Tags: Agents)

Create a new agent with the provided configuration. The full config supports transcriber, model, voice, web search, transfer, end-call conditions, post-call actions (email, webhook, Omni CRM, Cloud WhatsApp, or a workflow), ambient background track, initial ringing sound, and multilingual support.

Voicemail detection is an access-gated feature that we turn on per account. If it isn't enabled for yours yet, request access before configuring the voicemail object.

(Tags: Agents)

Get details of a specific agent by ID. The response also includes a can_publish boolean showing whether version history is turned on for the agent's organization. (Tags: Agents)

Update an existing agent. Send only the fields you want to change.

post_call_actions replaces the agent's email, webhook, Omni CRM, Cloud WhatsApp and workflow actions as one set, but only when you send at least one of those types. Google Sheets, Slack, Salesforce, HubSpot and Zoho Bigin actions are replaced only when their key is sent, and kept otherwise. If a sent action gives a variable key a new prompt, kept actions that use the same key take the new prompt too. To add, change or remove one action without touching the others, use /agents/{agent_id}/post-call-actions.

Voicemail detection is an access-gated feature that we turn on per account. If it isn't enabled for yours yet, request access before configuring the voicemail object below. (Tags: Agents)

Permanently delete an agent. (Tags: Agents)

List every post-call action on the agent, each with its own id. (Tags: Agents)

Add one post-call action to the agent. The agent's other actions are not changed. Send an Idempotency-Key header to make a retry safe: the same key and body return the action the first request added. (Tags: Agents)

Remove one post-call action from the agent. The agent's other actions are not changed. (Tags: Agents)

Change fields of one post-call action. Fields you don't send keep their value. The type cannot change. (Tags: Agents)

List the integrations connected to your workspace, with each one's id and integration_type. Stored credentials (tokens, secrets, passwords, API keys, and the values of a custom API's headers and parameters) are never returned: they read ********. When you create an integration, send the real values: ******** is refused. Accounts that sign in with OAuth (Google Sheets, Slack, HubSpot, Salesforce, Zoho Bigin) are connected in the dashboard. (Tags: Integrations)

List an agent's saved versions, newest first. Includes manual (named) versions, automatic versions, and system backups taken before a restore. (Tags: Agents)

Save the agent's current configuration as a named version. (Tags: Agents)

Delete a saved version. (Tags: Agents)

Rename a saved version or edit its note. Version history is immutable otherwise; only the name and note can change. (Tags: Agents)

Get a record-level diff for this version. By default it shows what changed in this version compared with the version before it. Use against=current to compare with the agent's live config (what restoring this version would change), or against=<number> to compare with another version. (Tags: Agents)

Restore a version onto the live agent. Your current setup is saved first as a backup version, so restoring is undoable. Configuration is brought back; any knowledge files or integrations that were deleted since this version was saved can't be re-linked, and are reported in skipped. (Tags: Agents)

Initiate a call to a phone number using a specified agent. The phone number must include a country code with a leading plus.

(Tags: Calls)

Retrieve call logs with pagination and optional filtering. (Tags: Calls)

Detailed information about a specific call (duration, status, transcript, sentiment, extracted variables). (Tags: Calls)

List bulk-call campaigns with pagination and optional status filter. (Tags: Bulk calls)

Create a new bulk-call campaign. Only name, phone_number_id and a contact_list are needed to dial a list now; every other field adds one behavior on top (drafts, rotation, filtering, scheduling, retries, dynamic feeding).

The guide below the field reference walks the whole journey: the first campaign and its response, each behavior with a working request, every refusal message with its fix, and the endpoints that operate a campaign once it runs.

(Tags: Bulk calls)

Push a single contact into a dynamic bulk-call campaign in real time. Dynamic campaigns are created from the dashboard (Bulk Call

Create New Campaign > Dynamic Campaign) and stay alive waiting for contacts, so this webhook is how you feed them from a CRM, form, or automation platform. The contact is queued immediately, and the campaign starts calling it as soon as it is within operating hours.

(Tags: Bulk calls)

Get detailed information about a bulk-call campaign. (Tags: Bulk calls)

Pause, resume, or reschedule a running campaign. (Tags: Bulk calls)

Cancel a scheduled bulk-call campaign. A campaign that is already running, or is still a draft, is refused. (Tags: Bulk calls)

Per-contact results for a campaign: what happened on each call, the variables you sent with that contact, and a pointer to the recording.

Paging

There is one rule. Call it with no cursor, then keep passing back the next_cursor you were handed until it comes back null.

cursor = None
while True:
    page = GET /lines?pagesize=150&cursor={cursor}
    handle(page["records"])
    cursor = page["next_cursor"]
    if not cursor: break

Each call returns a page of rows, oldest first: pagesize goes up to 150 and defaults to 30. Cursors are opaque, so pass back the string you were given and never build one. No contact is skipped or returned twice, even while the campaign is still dialing.

Transcripts are not in the row

Each row carries call.recording_id, not the conversation. Transcripts reach 212 KB, so carrying them here would make one page tens of megabytes. Fetch the one you want from GET /calls/logs/{recording_id}.

(Tags: Bulk calls)

The campaign's number pool, and which number is dialing right now.

calls_this_cycle is what fixed_count rotation compares against, so it is the field to watch for the next rotation. calls_dispatched is the number's lifetime total across every cycle.

(Tags: Bulk calls)

Add one of your numbers to the campaign's rotation pool. Works while the campaign is running, which is how you bring in a fresh number when the pool is running out of healthy ones.

The number must belong to you and must not already be in the pool. A number with no agent attached gets this campaign's agent attached automatically; a number attached to a different agent is refused.

(Tags: Bulk calls)

Stop or resume dialing from one number in the pool.

Pausing is what you want when a number starts going bad mid-campaign: dialing moves to the next number in sequence and the paused number keeps its history and counters. The last active number of a running campaign cannot be paused, since the campaign would have nothing to dial from.

Send the state you want rather than a toggle, so retrying the same request is harmless.

assignment_id is the number's id within this campaign's pool, from List rotation pool. It is not the phone_number_id.

(Tags: Bulk calls)

Add up to 1000 contacts to a campaign in one request.

This is the batch form of Add contact to dynamic campaign. Prefer it whenever you have more than a handful: one request of 500 contacts is far cheaper than 500 requests, on your side and ours.

Repeated numbers are kept, not merged. If the same number appears twice with different variables, it is called twice, because two rows for one number usually means two real reasons to call.

Rows that fail validation are reported in rejected and the rest are still added, so a single bad number does not lose the batch. A row that is missing a column the campaign's call_conditions need is reported in rejected; the condition values themselves are not evaluated on this route.

(Tags: Bulk calls)

Start a campaign that was created with save_as_draft: true.

Drafts let you build a campaign over several requests: create it, add contacts in batches, set the number pool, set concurrency, then start when everything is in place. A campaign that is already running, scheduled, or finished cannot be started.

(Tags: Bulk calls)

Change how many calls the campaign places at once, including while it is running. Raise it to finish sooner, lower it if your team cannot keep up with transfers or your numbers are being answered less.

The ceiling is your account's concurrency limit.

(Tags: Bulk calls)

Re-queue contacts that did not connect, without creating a new campaign.

Use it after a campaign finishes with more no-answers than you expected, or when the reason was on your side (a bad window, a number that was having a bad day). Retried contacts keep their original variables.

(Tags: Bulk calls)

Restrict a campaign to a daily calling window, in the campaign's timezone. Outside the window the campaign holds rather than finishing, and resumes the next day.

(Tags: Bulk calls)

Real-time status of a running bulk-call campaign. (Tags: Bulk calls)

List all knowledge-base files for the authenticated user. (Tags: Knowledge base)

Check whether a file can be uploaded based on size and type. (Tags: Knowledge base)

Upload a PDF file. The file content must be Base64 encoded. (Tags: Knowledge base)

Attach multiple knowledge-base files to an agent. (Tags: Knowledge base)

Detach multiple knowledge-base files from an agent. (Tags: Knowledge base)

Permanently delete a file. Removes it from any attached agents. Cannot be undone. (Tags: Knowledge base)

Retrieve the phone numbers on your account, whether you bought them from the OmniDimension number shop or imported your own.

(Tags: Phone numbers)

Search the OmniDimension number shop for phone numbers available to buy in a region. Price and validity are flat per region, so every result shows the same monthly_rental_usd and validity_days, and that is the exact amount a purchase will charge.

A region can have more than one carrier, each stocking different number series. Pass the carrier you want; the response names the carrier its results came from, and that is the carrier a purchase has to pass.

(Tags: Phone numbers)

Buy a phone number from the OmniDimension number shop. The monthly rental comes out of your wallet and the number is added to your account, ready to attach to an agent.

(Tags: Phone numbers)

Give up a phone number and stop its rental, so it is not charged at the next renewal. Only a number currently allocated to the account can be released.

(Tags: Phone numbers)

Attach a phone number to an existing agent. (Tags: Phone numbers)

Detach a phone number from its agent. (Tags: Phone numbers)

Import an existing Twilio number by providing your Twilio credentials. (Tags: Phone numbers)

Import an Exotel number by providing your Exotel credentials. (Tags: Phone numbers)

Import a phone number associated with a SIP trunk. (Tags: Phone numbers)

Retrieve all available Large Language Model providers. (Tags: Providers)

Retrieve voices with filtering and pagination support. ElevenLabs and Cartesia support advanced filtering by name, language, accent, and gender. Other providers support basic pagination only.

(Tags: Providers)

Retrieve all Speech-to-Text providers. (Tags: Providers)

Retrieve all Text-to-Speech providers. (Tags: Providers)

Comprehensive response with services and voices in one payload. (Tags: Providers)

Detailed metadata for a specific voice. (Tags: Providers)

Read your organization's wallet: the remaining balance, the minutes it buys at your rates, your plan, your concurrency headroom, and whether auto-recharge will refill it.

Use it before a campaign, or on a schedule, so you find out you are low on credit from this endpoint rather than from a call failing with 402 payment_required.

The response always describes the organization the API key belongs to. There is no parameter for reading another account; resellers read a client's figures through the Reseller endpoints.

A balance at or below zero does not always mean calls will stop. An organization on usage-based billing (plan.is_usage_based) keeps placing calls and is metered to its payment method instead, so check that flag before treating a zero balance as a stop condition.

The API key's user needs Billing access in your organization. If you get a 403, an administrator can grant it when Billing is enabled for your organization; when it is not, contact support.

(Tags: Account)

Your cloned voices, oldest first, one cursor page at a time. Call it with no cursor, then pass back the next_cursor you were handed until it is null.

Once a voice is ready, its voice_id is the provider voice id to put in an agent's voice.voice_id with voice.provider: cartesia.

(Tags: Voice cloning)

Clone a voice from an audio sample. The sample must be Base64 encoded and 1 KB to 25 MB. MP3, WAV and WebM are accepted; a non-audio body is refused.

Creation is asynchronous. This call returns 202 at once with status: processing. Poll GET /voices/{voice_id} until status is ready or failed, then use the voice_id in an agent's voice config with voice.provider: cartesia.

You must send consent: true: you confirm you have the right to clone this voice. The attestation is recorded against the clone.

Limits apply per user: 5 clones an hour, 20 a day, and 200 stored (processing plus ready). A request over a limit is refused with 429.

(Tags: Voice cloning)

One cloned voice, including its creation status. (Tags: Voice cloning)

Delete a cloned voice and remove it from the provider. A voice that is still processing cannot be deleted.

(Tags: Voice cloning)

Change the name, description or gender of a cloned voice. (Tags: Voice cloning)

Stream the generated mp3 sample of a cloned voice. Only the owner can fetch it. 404 (sample_not_ready) when no sample exists yet. The request needs your API key in the Authorization header.

(Tags: Voice cloning)

Regenerate the sample audio for a ready voice. (Tags: Voice cloning)

Search the node types a workflow can use, such as whatsapp, voice_ai or conditional. Call it first when you do not know which node to add. Then call getWorkflowNodeType for the settings of one type.

(Tags: Workflows)

The settings one node type reads, with their types, required flags and outputs. Call it before you add or edit a node, because its fields are the keys of the node's config. Use detail=full only when you need help text and examples.

(Tags: Workflows)

The choices for one ref field of a node type, such as the phone numbers, agents or integrations in your account. Call it for every ref field and never guess an id. If it returns 400 no_options, the field is not chosen from a list, so ask the user for the value.

(Tags: Workflows)

Your workflows, oldest first, one cursor page at a time. Use it to find a workflow id. Pass back next_cursor until it is null.

(Tags: Workflows)

Create a workflow with a draft. Without graph, the draft holds one trigger node, ready for editWorkflow ops. Pass graph only to start from a complete graph. The response carries the revision you need to edit.

(Tags: Workflows)

One workflow with its draft, status and revision. Call it before every edit to get the current revision. Use view=structure to see nodes and edges without config on a large workflow. Secrets read back as ********.

(Tags: Workflows)

Delete a workflow. Its published version stops running. This cannot be undone, so confirm with the user first. To stop it without deleting, use deactivateWorkflow.

(Tags: Workflows)

Change the draft with a list of ops: add, update, move or delete nodes, and connect or disconnect them. The ops apply all together or not at all. You must send the revision from your last read. If you get 409 revision_conflict, read the workflow again and retry. Secrets read back as ********. Send them back unchanged to keep the stored value. This edits the draft only. Use publishWorkflow to make it live.

(Tags: Workflows)

Check the draft and list what blocks publish. It changes nothing. Call it after your edits and fix every error before publishWorkflow.

(Tags: Workflows)

Make the draft the live version. Real events then run it, unless the workflow is paused. Run validateWorkflow first: publish is refused while the draft has errors. Ask the user before you publish.

(Tags: Workflows)

Turn the published workflow on, so real events run it. Use it to resume a workflow you paused with deactivateWorkflow.

(Tags: Workflows)

Turn the published workflow off, so real events stop running it. The workflow and its draft stay. Use activateWorkflow to turn it back on.

(Tags: Workflows)

Runs the draft once with payload as the trigger data. Every node runs for real: WhatsApp messages, SMS, emails and calls go out and CRM records change. Ask the user before calling it, and use their own phone number or email in the payload.

It returns an execution_id at once. Poll getWorkflowExecution for the result.

(Tags: Workflows)

One run of a workflow, with the result of each step. Use it to read the outcome of testWorkflow. A run is finished when state is completed, failed or cancelled.

(Tags: Workflows)