# Revox API

> Revox places AI phone calls. With the REST API you create voice assistants (prompt, voice, first sentence, data to extract), call one number or a whole list (campaigns), and read each call's outcome, transcript, recording and extracted data. An MCP server gives AI clients the main workflow (assistants, voices, calendars, single calls) as tools.

**Essentials**

- Base URL `https://www.getrevox.com/api`. JSON in and out: send `Content-Type: application/json` with every body. Endpoints marked "No body" take none.
- Auth: `Authorization: Bearer <API key>` on every request. A key belongs to one organization; create it in the dashboard (API keys).
- Revox IDs are UUIDs (a voice id is its provider's). Phone numbers are E.164 (`+33612345678`). Timestamps are ISO 8601 UTC ending in `Z`; offsets are rejected.
- Errors: `{ "error": string }`, or `{ "message": string }` for validation failures and unexpected errors. `400` validation (`bodyErrors.issues[]` gives each `path` and `message`) or a refused request, `401` bad key, `402` out of credits, `404` not in your organization, `409` conflicts with the current state.
- Unknown body fields are ignored without an error: copy field names from the pages.
- Endpoints with rules the schema cannot express have a "Before you call" section: read it before sending.
- MCP server: `https://www.getrevox.com/api/mcp-servers/generic/mcp` (assistants, voices, calendars, single calls and their results as tools; running campaigns, phone numbers and exports are REST only). SDKs: `npm install @revoxai/sdk`, `pip install revox`, `gem install revox`.

**Recipes**

- Call a number and get the result: `POST /call` with `phone_number`, `assistant_id` and `prompt_variables`, then poll `GET /call/{id}` until `status` is `completed`, `cancelled` or `errored` (or use the webhook); read `call.outcome` and `call.last_call_attempt` (transcript, recording, `structured_output`).
- Create an assistant that speaks a language: `GET /voices`, keep a voice whose `language` is the target (`"fr"`), then `POST /assistants` with `name`, a `prompt` written in that language and `voice: {provider, id}`.
- Call a list of contacts: `POST /campaigns` with `name`, `assistant_id` and `contacts` (nothing is dialed yet), then `POST /campaigns/{id}/launch-calls` with `{"mode": "ai_first", "selection": {"filters": {}}}` (every contact, now).
- Find calls by outcome: `POST /call/search` with `outcomes: ["interested"]`; `page` and `page_size` are body fields. There is no date filter: sort by `updated_at` and stop at the first call older than your cutoff.
- Change an assistant's voice or model: `PATCH /assistants/{id}` with `voice` and `llm_model: {"type": "gpt-4.1-priority"}`; only the fields you send change.
- Let an assistant book meetings: `POST /assistants/{id}/calendars` with a `provider`, create an invite link for the account owner, poll the calendars until `status` is `ready`, then mention the calendar's `@handle` in the prompt.

The links of the sections below are Markdown pages (the Optional section also has the full file and the OpenAPI document).

## Guides

- [Overview](https://www.getrevox.com/docs/api.md): authentication, quickstart, conventions, errors
- [MCP server](https://www.getrevox.com/docs/api/mcp.md): connect an AI client; every tool listed
- [Webhooks](https://www.getrevox.com/docs/api/webhooks.md): when Revox POSTs a finished call to you, and the payload

## Authentication

- [Check an API key](https://www.getrevox.com/docs/api/authentication/check-an-api-key.md): `GET /auth-status`. Check that your API key is valid, e.g. before storing it: a 200 with authenticated true means it is; any other answer means the key was not accepted.

## Calls

- [Place a call](https://www.getrevox.com/docs/api/calls/place-a-call.md): `POST /call`. Place an outbound call with a saved assistant (assistant_id) or a configuration for this call only (assistant).
- [Get call by ID](https://www.getrevox.com/docs/api/calls/get-call-by-id.md): `GET /call/{id}`. Returns a call with its status, outcome and attempts, each with its transcript, recording and extracted data.
- [Find which phone numbers are on the do-not-call list](https://www.getrevox.com/docs/api/calls/find-which-phone-numbers-are-on-the-do-not-call-list.md): `POST /calls/screen-do-not-call`. Returns the subset of the submitted numbers that must not be called.
- [Search calls](https://www.getrevox.com/docs/api/calls/search-calls.md): `POST /call/search`. Search your organization's calls, most recent activity first by default.
- [Get a link to listen to a live call and jump in](https://www.getrevox.com/docs/api/calls/get-a-link-to-listen-to-a-live-call-and-jump-in.md): `POST /call/{id}/live-link`. Returns a short-lived web page URL for one call that is ringing or on the line.
- [Export calls history](https://www.getrevox.com/docs/api/calls/export-calls-history.md): `POST /call/export`. Export calls as a CSV file, one line per call, selected with the filters of [`POST /call/search`](https://www.getrevox.com/docs/api/calls/search-calls.md).
- [Pause a call](https://www.getrevox.com/docs/api/calls/pause-a-call.md): `POST /call/{id}/pause`. Pause a call waiting for its next attempt (status scheduled or initializing): nothing is dialed until [`POST /call/{id}/resume`](https://www.getrevox.com/docs/api/calls/resume-a-paused-call.md).
- [Resume a paused call](https://www.getrevox.com/docs/api/calls/resume-a-paused-call.md): `POST /call/{id}/resume`. Resume a previously paused call.
- [Cancel a call](https://www.getrevox.com/docs/api/calls/cancel-a-call.md): `POST /call/{id}/cancel`. Stop a call's future attempts.
- [Get phone number history across the organization](https://www.getrevox.com/docs/api/calls/get-phone-number-history-across-the-organization.md): `GET /calls/phone-history`. Returns a map of phone numbers to the number of calls and associated campaigns across the entire organization.
- [The Call object](https://www.getrevox.com/docs/api/objects/call.md): One order to call one phone number with an assistant.
- [The CallAttempt object](https://www.getrevox.com/docs/api/objects/call-attempt.md): One dial of a call's phone number, with what answered, the transcript, the recording and the extracted data.
- [The CallRetryConfigOverride object](https://www.getrevox.com/docs/api/objects/call-retry-config-override.md): Retry settings for this call only, over the assistant's call_retry_config (or the campaign's, when the call names a campaign).

## Assistants

- [Create an assistant](https://www.getrevox.com/docs/api/assistants/create-an-assistant.md): `POST /assistants`. Create a voice agent: the prompt the LLM follows, how it opens the call, its voice (Cartesia, ElevenLabs and Gradium), the data to extract after each call and where to post the result.
- [Get assistant by ID](https://www.getrevox.com/docs/api/assistants/get-assistant-by-id.md): `GET /assistants/{id}`. Retrieve a single assistant by its unique ID.
- [Get assistants](https://www.getrevox.com/docs/api/assistants/get-assistants.md): `GET /assistants`. Retrieve all assistants associated with your account.
- [Check an assistant's setup](https://www.getrevox.com/docs/api/assistants/check-an-assistants-setup.md): `POST /assistants/{id}/setup-check`. Check a saved assistant for the setup mistakes that break real calls: a persona whose gender doesn't match the voice, a prompt that transfers or books with no transfer destination or calendar connected, template text left in, the wrong language, wording that reads wrong once variables are filled.
- [Update an assistant](https://www.getrevox.com/docs/api/assistants/update-an-assistant.md): `PATCH /assistants/{id}`. Update one or more fields of an assistant: only the fields you send change.
- [Delete an assistant](https://www.getrevox.com/docs/api/assistants/delete-an-assistant.md): `DELETE /assistants/{id}`. Permanently delete an assistant by its ID.
- [Clone an assistant](https://www.getrevox.com/docs/api/assistants/clone-an-assistant.md): `POST /assistants/{id}/clone`. Create a copy of an assistant with its whole configuration and its calendars (on the same connected accounts), named after it with " (Copy)" appended.
- [Turn the public demo page on or off](https://www.getrevox.com/docs/api/assistants/turn-the-public-demo-page-on-or-off.md): `POST /assistants/{id}/demo-page`. The demo page lets anyone with its link call the assistant and see the calls it placed, with their transcripts and recordings.
- [Get assistant statistics](https://www.getrevox.com/docs/api/assistants/get-assistant-statistics.md): `GET /assistants/{id}/statistics`. Report on the inbound calls the assistant received, whatever their status: the total, the weekly volume over the last 12 weeks and the weekly average since the assistant went into service, the weekday and hour they arrive, and how long the answered ones lasted.
- [Add a calendar to an assistant](https://www.getrevox.com/docs/api/assistants/add-a-calendar-to-an-assistant.md): `POST /assistants/{id}/calendars`. Add a calendar on a provider, before any account is connected to it.
- [Create an invite link for a calendar](https://www.getrevox.com/docs/api/assistants/create-an-invite-link-for-a-calendar.md): `POST /assistants/{id}/calendars/{calendarId}/invite`. A link for the owner of an account to connect it to the calendar, on the calendar's provider, without a Revox account: give them invite.url.
- [List an assistant's calendars](https://www.getrevox.com/docs/api/assistants/list-an-assistants-calendars.md): `GET /assistants/{id}/calendars`. The calendars the assistant books meetings on during a call, in the order they were added.
- [List what a calendar can book on](https://www.getrevox.com/docs/api/assistants/list-what-a-calendar-can-book-on.md): `GET /assistants/{id}/calendars/{calendarId}/options`. The calendars (Google) or event types (Calendly, Cal.com) of the account connected to the calendar, to pick the one it books on with PUT .../selection.
- [Change a calendar's settings](https://www.getrevox.com/docs/api/assistants/change-a-calendars-settings.md): `PATCH /assistants/{id}/calendars/{calendarId}`. The settings of its provider: opening hours, meeting length and Meet link for Google Calendar, the event type for Calendly and Cal.com.
- [Connect an account to a calendar](https://www.getrevox.com/docs/api/assistants/connect-an-account-to-a-calendar.md): `PUT /assistants/{id}/calendars/{calendarId}/connection`. Connect the calendar to an account your organization already uses on its provider.
- [Remove a calendar from an assistant](https://www.getrevox.com/docs/api/assistants/remove-a-calendar-from-an-assistant.md): `DELETE /assistants/{id}/calendars/{calendarId}`. The agent stops booking on it.
- [Disconnect a calendar's account](https://www.getrevox.com/docs/api/assistants/disconnect-a-calendars-account.md): `DELETE /assistants/{id}/calendars/{calendarId}/connection`. The calendar keeps its handle, which the agent then treats as not available, and waits for an account.
- [Revoke a calendar's invite link](https://www.getrevox.com/docs/api/assistants/revoke-a-calendars-invite-link.md): `DELETE /assistants/{id}/calendars/{calendarId}/invite`. The calendar's invite link stops working right away, and its `invite` becomes null.
- [Pick what a calendar books on](https://www.getrevox.com/docs/api/assistants/pick-what-a-calendar-books-on.md): `PUT /assistants/{id}/calendars/{calendarId}/selection`. Set the calendar (Google) or event type (Calendly, Cal.com) of the connected account the calendar books on, with an id from GET .../options.
- [List an assistant's pronunciations](https://www.getrevox.com/docs/api/assistants/list-an-assistants-pronunciations.md): `GET /assistants/{id}/pronunciations`. The words the assistant's voice must say a specific way, with the text sent to the voice in their place.
- [Set how the voice says a word](https://www.getrevox.com/docs/api/assistants/set-how-the-voice-says-a-word.md): `PUT /assistants/{id}/pronunciations`. Stores the version of a word the user chose by ear.
- [Remove a pronunciation](https://www.getrevox.com/docs/api/assistants/remove-a-pronunciation.md): `DELETE /assistants/{id}/pronunciations/{pronunciationId}`. The voice says the word as written again.
- [Suggest versions of a word to choose by ear](https://www.getrevox.com/docs/api/assistants/suggest-versions-of-a-word-to-choose-by-ear.md): `POST /assistants/{id}/pronunciations/suggest`. Hears how the word must sound (a recording of someone saying it, or `sounds_like`), writes up to five ways to spell it for the assistant's voice, the word as written first, and returns each one said by that voice in `sentence`.
- [Hear the voice say a word or one of its versions](https://www.getrevox.com/docs/api/assistants/hear-the-voice-say-a-word-or-one-of-its-versions.md): `POST /assistants/{id}/pronunciations/say`. Returns the assistant's voice saying `text` exactly as sent, without applying any of its pronunciations: the word as written is how callers hear it before one is set.
- [The Assistant object](https://www.getrevox.com/docs/api/objects/assistant.md): The voice agent that places and answers calls: its prompt, voice and LLM, how it opens and ends a call, the data it extracts, and the tools and calendars it uses.
- [The AssistantCalendar object](https://www.getrevox.com/docs/api/objects/assistant-calendar.md): A calendar an assistant books meetings on during calls: one provider, one connected account, and the calendar or event type of that account it books on.
- [The AssistantSetupIssue object](https://www.getrevox.com/docs/api/objects/assistant-setup-issue.md): A setup mistake found by [`POST /assistants/{id}/setup-check`](https://www.getrevox.com/docs/api/assistants/check-an-assistants-setup.md), with the edit that fixes it when one is known.
- [The CallRetryConfig object](https://www.getrevox.com/docs/api/objects/call-retry-config.md): When and how often a call is dialed: the calling windows and allowed days, the delay between two attempts and the maximum number of attempts.
- [The StructuredOutputField object](https://www.getrevox.com/docs/api/objects/structured-output-field.md): One value to extract from a call (an entry of an assistant's structured_output_config), or one parameter of a custom tool (an entry of its input_schema).

## Campaigns

- [Create a campaign](https://www.getrevox.com/docs/api/campaigns/create-a-campaign.md): `POST /campaigns`. Create an outbound calling campaign.
- [Get campaign by ID](https://www.getrevox.com/docs/api/campaigns/get-campaign-by-id.md): `GET /campaigns/{id}`. Retrieve the full details of a single campaign by its unique ID.
- [List campaigns](https://www.getrevox.com/docs/api/campaigns/list-campaigns.md): `GET /campaigns`. Retrieve all campaigns for your organization, including both active and completed ones.
- [Update a campaign](https://www.getrevox.com/docs/api/campaigns/update-a-campaign.md): `PATCH /campaigns/{id}`. Update a campaign's name, outbound number, retry configuration (calling hours, retry delay, max attempts) and concurrency cap.
- [Delete a campaign](https://www.getrevox.com/docs/api/campaigns/delete-a-campaign.md): `DELETE /campaigns/{id}`. Permanently delete a campaign and all its associated rows.
- [Launch a campaign's calls](https://www.getrevox.com/docs/api/campaigns/launch-a-campaigns-calls.md): `POST /campaigns/{id}/launch-calls`. Send the campaign's calls matching a selection.
- [Cancel a campaign](https://www.getrevox.com/docs/api/campaigns/cancel-a-campaign.md): `POST /campaigns/{id}/cancel`. Cancel a running or scheduled campaign.
- [Pause a running campaign](https://www.getrevox.com/docs/api/campaigns/pause-a-running-campaign.md): `POST /campaigns/{id}/pause`. Pause a running campaign so no further calls are placed.
- [Resume a paused campaign](https://www.getrevox.com/docs/api/campaigns/resume-a-paused-campaign.md): `POST /campaigns/{id}/resume`. Resume a paused campaign.
- [Export campaign rows](https://www.getrevox.com/docs/api/campaigns/export-campaign-rows.md): `GET /campaigns/{id}/export`. Export all rows of a campaign as a CSV file for offline analysis or reporting.
- [Get campaign statistics](https://www.getrevox.com/docs/api/campaigns/get-campaign-statistics.md): `GET /campaigns/{id}/statistics`. Campaign report: a four-step funnel (contacts called, reached, real conversations, hot leads), the calling effort, inbound calls, the calls your team joined live, the outcome breakdown and the hot leads to follow up.
- [Add contacts to a campaign](https://www.getrevox.com/docs/api/campaigns/add-contacts-to-a-campaign.md): `POST /campaigns/{id}/rows`. Append contacts to an existing campaign.
- [Get campaign rows](https://www.getrevox.com/docs/api/campaigns/get-campaign-rows.md): `GET /campaigns/{id}/rows`. Retrieve all contact rows for a campaign.
- [The Campaign object](https://www.getrevox.com/docs/api/objects/campaign.md): A list of contacts called by one assistant, with its calling windows, retries and concurrency cap, and where its contacts stand.

## Voices

- [Get voice by ID](https://www.getrevox.com/docs/api/voices/get-voice-by-id.md): `GET /voices/{id}`. Retrieve details for a single voice by its unique ID and provider.
- [Get voices](https://www.getrevox.com/docs/api/voices/get-voices.md): `GET /voices`. Retrieve all voices available for AI calls: the preset voices from Cartesia, ElevenLabs and Gradium, and your organization's cloned voices.
- [Delete a voice](https://www.getrevox.com/docs/api/voices/delete-a-voice.md): `DELETE /voices/{id}`. Delete a cloned voice.
- [Generate voice preview](https://www.getrevox.com/docs/api/voices/generate-voice-preview.md): `POST /voices/preview`. Generate a short audio sample of a voice.
- [Clone a voice](https://www.getrevox.com/docs/api/voices/clone-a-voice.md): `POST /voices/clone`. Clone a voice from an audio recording.
- [The Voice object](https://www.getrevox.com/docs/api/objects/voice.md): A voice an assistant can speak with: a preset voice of its provider, or a voice your organization cloned.

## Phone Numbers

- [Get phone numbers](https://www.getrevox.com/docs/api/phone-numbers/get-phone-numbers.md): `GET /phone-numbers`. List the phone numbers of your organization: the numbers calls can be placed from (from_phone_number) and received on, with the assistant that answers each one's inbound calls and its spam reputation.
- [Update a phone number](https://www.getrevox.com/docs/api/phone-numbers/update-a-phone-number.md): `PATCH /phone-numbers/{id}`. Rename a phone number, or choose which assistant answers its inbound calls.
- [Delete a phone number](https://www.getrevox.com/docs/api/phone-numbers/delete-a-phone-number.md): `DELETE /phone-numbers/{id}`. Remove a phone number from your organization: no call can be placed from it or received on it through Revox anymore.
- [The PhoneNumber object](https://www.getrevox.com/docs/api/objects/phone-number.md): A phone number of your organization: a caller ID for outbound calls and, for an owned number, a line whose inbound calls an assistant can answer.

## Users

- [Get the current user](https://www.getrevox.com/docs/api/users/get-the-current-user.md): `GET /users/me`. Get the user the API key or session belongs to, with their organization ID.
- [The User object](https://www.getrevox.com/docs/api/objects/user.md): The current authenticated user.
- [The OrgMember object](https://www.getrevox.com/docs/api/objects/org-member.md): A member of the current organization.

## Usage

- [Get credit and call usage](https://www.getrevox.com/docs/api/usage/get-credit-and-call-usage.md): `GET /usage`. Credits used, calls placed, calls answered and time on the line over a period, point by point and per assistant and campaign, compared with the period just before.
- [The Usage object](https://www.getrevox.com/docs/api/objects/usage.md)

## Optional

- [Everything in one file](https://www.getrevox.com/docs/api/llms-full.txt)
- [OpenAPI 3.1 document](https://www.getrevox.com/openapi.json)