# Revox API

Revox places AI phone calls. You describe the conversation in an **assistant** (prompt, voice, first sentence, what to extract after the call), then ask Revox to **call** a phone number with it, one call at a time or in **campaigns** of thousands of contacts. After the call you get the outcome, the transcript, the recording and the data the assistant extracted.

These docs are written for developers and for AI agents. Every page exists in Markdown: add `.md` to its URL. The whole reference in one file is at [https://www.getrevox.com/docs/api/llms-full.txt](https://www.getrevox.com/docs/api/llms-full.txt), the index at [https://www.getrevox.com/docs/api/llms.txt](https://www.getrevox.com/docs/api/llms.txt), and the OpenAPI 3.1 document at [https://www.getrevox.com/openapi.json](https://www.getrevox.com/openapi.json).

## Base URL

```
https://www.getrevox.com/api
```

Requests and responses are JSON. Send `Content-Type: application/json` with every body.

## Authentication

Every request carries an API key as a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

Create a key in the dashboard, under [API keys](https://www.getrevox.com/dashboard?goto=api-keys). A key belongs to one organization: everything you create with it (assistants, calls, campaigns) lives in that organization. Keep it on your server, never in a browser or a mobile app. [GET /auth-status](/docs/api/authentication) tells you whether a key is valid.

## Quickstart: place a call and get its result

1. **Create an assistant** with [POST /assistants](/docs/api/assistants/create-an-assistant): a `name`, a `prompt` and a voice. You can skip this step and pass an inline `assistant` object when you place the call.
2. **Place the call** with [POST /call](/docs/api/calls/place-a-call): the `phone_number` in E.164 format (`+33612345678`) and the `assistant_id`. Use `prompt_variables` to fill the `{{variables}}` of the prompt for this contact. The response holds the `call` with its `id`.
3. **Get the result**, either way:
   - poll [GET /call/{id}](/docs/api/calls/get-call-by-id) every few seconds until `is_completed` is `true`;
   - or set a `webhook_url` on the assistant: Revox POSTs the call to it when the call ends (see [Webhooks](/docs/api/webhooks)).

A call is an order that may take several attempts: if nobody answers, Revox calls back following the assistant's `call_retry_config`, within its calling windows. Each attempt is in `call_attempts`, with its transcript and recording; `outcome` and the extracted data describe the whole call.

## Calling many contacts

Create a [campaign](/docs/api/campaigns/create-a-campaign) with an assistant and its contacts, then [launch its calls](/docs/api/campaigns/launch-a-campaigns-calls). Revox paces them (`max_concurrent_calls`), respects calling windows and retries, and keeps per-campaign [statistics](/docs/api/campaigns/get-campaign-statistics).

## Errors

Errors use standard HTTP status codes and a JSON body with an `error` (or `message`) string:

- `400`: the body or a parameter failed validation. `bodyErrors.issues` lists each invalid field with its `path`.
- `401`: the API key is missing or invalid.
- `402`: the organization has run out of credits.
- `404`: the resource does not exist in your organization.

## For AI agents

- Prefer the [MCP server](/docs/api/mcp) when your client speaks MCP: it wraps this API in tools, guides prompt writing and can wait for a call to finish.
- Otherwise fetch the Markdown of the page you need (add `.md` to the URL) or the whole reference at [https://www.getrevox.com/docs/api/llms-full.txt](https://www.getrevox.com/docs/api/llms-full.txt).
- Field descriptions are the source of truth: they say what `null` and an omitted field mean when the two differ.

## Reference

### Authentication
- [GET /auth-status](https://www.getrevox.com/docs/api/authentication/get-auth-status.md): `GET /auth-status`. Check if your API key is still valid.

### Assistants
- [Get assistants](https://www.getrevox.com/docs/api/assistants/get-assistants.md): `GET /assistants`. Retrieve all assistants associated with your account.
- [Create an assistant](https://www.getrevox.com/docs/api/assistants/create-an-assistant.md): `POST /assistants`. Create a new AI assistant with a custom prompt, voice, and behavior configuration.
- [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.
- [Update an assistant](https://www.getrevox.com/docs/api/assistants/update-an-assistant.md): `PATCH /assistants/{id}`. Update one or more fields on an existing assistant.
- [Delete an assistant](https://www.getrevox.com/docs/api/assistants/delete-an-assistant.md): `DELETE /assistants/{id}`. Permanently delete an assistant by its ID.
- [Get assistant statistics](https://www.getrevox.com/docs/api/assistants/get-assistant-statistics.md): `GET /assistants/{id}/statistics`. Retrieve the "Statistiques" report for an assistant's inbound activity: total calls received with a 12-week activity chart, the weekday and hour distribution, and the duration breakdown of answered calls.
- [Clone an assistant](https://www.getrevox.com/docs/api/assistants/clone-an-assistant.md): `POST /assistants/{id}/clone`. Create a full copy of an existing assistant, including every configuration field.
- [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.
- [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.
- [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.
- [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.
- [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.
- [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`. Attach a Nango connection of the organization to the calendar, which takes the handle of that account (`google_calendar_aric_at_getrevox.com`, then `_2` for a second calendar on the same account).
- [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.
- [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 a colleague without a Revox account to connect their own account on the calendar's provider.
- [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`.

### Calls
- [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.
- [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.
- [Get call by ID](https://www.getrevox.com/docs/api/calls/get-call-by-id.md): `GET /call/{id}`. Retrieve the full details of a call order by its unique ID.
- [Place a call](https://www.getrevox.com/docs/api/calls/place-a-call.md): `POST /call`. Place a new outbound call order.
- [Get calls](https://www.getrevox.com/docs/api/calls/get-calls.md): `POST /call/search`. Retrieve a paginated list of call attempts.
- [Export calls history](https://www.getrevox.com/docs/api/calls/export-calls-history.md): `POST /call/export`. Export a list of call attempts as a CSV file.
- [Pause a call](https://www.getrevox.com/docs/api/calls/pause-a-call.md): `POST /call/{id}/pause`. Pause a call's retry loop.
- [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.

### Campaigns
- [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.
- [Create a campaign](https://www.getrevox.com/docs/api/campaigns/create-a-campaign.md): `POST /campaigns`. Create a new 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.
- [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.
- [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.
- [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.
- [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.
- [Get campaign statistics](https://www.getrevox.com/docs/api/campaigns/get-campaign-statistics.md): `GET /campaigns/{id}/statistics`. Retrieve the "Statistiques" report for a campaign: the four-tile cascade funnel (appelés → eus en ligne → réels échanges → leads chauds), two secondary tiles, the distribution of exchanges by outcome, the list of hot leads, and data-extraction coverage.
- [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.

### Voices
- [Get voices](https://www.getrevox.com/docs/api/voices/get-voices.md): `GET /voices`. Retrieve all voices available for AI calls, including preset voices from Cartesia/ElevenLabs and your organization's cloned 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.
- [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 preview for a given 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.

### Phone Numbers
- [Get phone numbers](https://www.getrevox.com/docs/api/phone-numbers/get-phone-numbers.md): `GET /phone-numbers`.
- [Update a phone number](https://www.getrevox.com/docs/api/phone-numbers/update-a-phone-number.md): `PATCH /phone-numbers/{id}`.
- [Delete a phone number](https://www.getrevox.com/docs/api/phone-numbers/delete-a-phone-number.md): `DELETE /phone-numbers/{id}`.

### Users
- [GET /users/me](https://www.getrevox.com/docs/api/users/get-users-me.md): `GET /users/me`. Get the current authenticated user.
- [PATCH /users/me](https://www.getrevox.com/docs/api/users/patch-users-me.md): `PATCH /users/me`. Update the current authenticated user.

### Objects
- [Assistant](https://www.getrevox.com/docs/api/objects/assistant.md)
- [AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md)
- [AssistantSetupIssue](https://www.getrevox.com/docs/api/objects/assistant-setup-issue.md)
- [Call](https://www.getrevox.com/docs/api/objects/call.md)
- [CallAttempt](https://www.getrevox.com/docs/api/objects/call-attempt.md)
- [CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md)
- [CallSpeechEvent](https://www.getrevox.com/docs/api/objects/call-speech-event.md)
- [Campaign](https://www.getrevox.com/docs/api/objects/campaign.md)
- [OrgMember](https://www.getrevox.com/docs/api/objects/org-member.md)
- [PhoneNumber](https://www.getrevox.com/docs/api/objects/phone-number.md)
- [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md)
- [User](https://www.getrevox.com/docs/api/objects/user.md)
- [Voice](https://www.getrevox.com/docs/api/objects/voice.md)

### Guides
- [Webhooks](https://www.getrevox.com/docs/api/webhooks.md)
- [MCP server](https://www.getrevox.com/docs/api/mcp.md)