# Revox API documentation

---

## 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)

---

## MCP server

Revox runs an MCP server (Model Context Protocol) that exposes this API as tools. Connect Claude, ChatGPT, Cursor, Codex or any MCP client to it and ask in plain words: create an assistant, pick its voice, connect a calendar, place a test call.

### Server URL

```
https://www.getrevox.com/api/mcp-servers/generic/mcp
```

Streamable HTTP transport. If you belong to several organizations, use the organization's own URL, shown in the dashboard on the [MCP page](https://www.getrevox.com/dashboard?goto=mcp), which also has one-click setup for each client.

### Authentication

- **OAuth**: clients that support it (Claude, ChatGPT, Cursor) open a Revox sign-in window the first time. Nothing to configure.
- **API key**: send `Authorization: Bearer YOUR_API_KEY`, the same key as the REST API.

### How the tools work together

The server sends these instructions to the client on connection:

> Revox places AI phone calls and manages the voice assistants that make them.
>
> Before writing or changing an assistant's prompt (revox_create_assistant, or revox_update_assistant with prompt or first_sentence), call revox_get_prompt_guide and follow it: it is Revox's prompt-creation guide for phone conversations (identity and opener, turns, qualification, objections, actions, end of call). Pass its guide_version as prompt_guide_version: those tools refuse a prompt without it.
>
> After your last change to an assistant, call revox_check_assistant_setup and fix what it reports before handing the assistant over.
>
> To place a call, use revox_make_call, then revox_wait_for_call to get the outcome, transcript and extracted data.
>
> You cannot play audio: to choose a voice, call revox_pick_voice and give the user its url, then revox_wait_for_voice_pick. After creating or updating an assistant, give the user its test_url to try it live in the browser.
>
> You cannot sign in to a calendar account: to add a calendar, call revox_connect_calendar and give the user its url, then revox_wait_for_calendar. revox_list_assistant_tools lists what an assistant's prompts can mention as @name, including its calendars.

### Tools

#### `revox_auth_status`

Check if the API key is valid.

#### `revox_create_api_key`

Create a Revox API key for the organization, to configure another tool or service (env var, CI secret, integration). The full key is returned only in this response and no tool can show it again: store it right away where it is needed, do not repeat it to the user unless they ask. The user can revoke it from dashboard_url.

Arguments: `name`.

#### `revox_get_call`

Get a call by ID. Use this to poll for completion after revox_make_call (MCP has no webhooks).

Arguments: `id`.

#### `revox_wait_for_call`

Poll a call until it completes, is cancelled, or the server time window expires (~240 s). If the result contains `_retry: true`, call this tool again with the same id to keep waiting.

Arguments: `id`, `poll_interval_secs`.

#### `revox_make_call`

Place a call. Returns immediately with call id. Provide either assistant_id or prompt (not both). With assistant_id, personalize the call with prompt_variables (the assistant's {{variables}}); the assistant's own config is used and the inline fields (prompt, voice, first sentence, structured output, webhook, custom tools...) are ignored. With prompt, the inline fields configure this one call. Voice is optional: if voice_provider/voice_id are omitted, a voice is auto-selected based on the target phone number's country (e.g. a French number gets a French voice). Use metadata to attach your own ids, from_phone_number to choose the caller ID, scheduled_at to call later. To know when the call is done, use revox_wait_for_call or poll revox_get_call manually: the result carries the outcome, summary, transcript, extracted structured_output and the tools the agent ran.

Arguments: `phone_number`, `prompt_variables`, `metadata`, `from_phone_number`, `scheduled_at`, `concurrency`, `skip_calling_window`, `timezone`, `assistant_id`, `prompt`, `voice_provider`, `voice_id`, `voice_volume`, `first_sentence`, `first_sentence_mode`, `end_of_call_sentence`, `voicemail_message`, `max_call_duration_secs`, `structured_output_config`, `structured_output_prompt`, `webhook_url`, `custom_tools`, `post_call_prompt`, `transfer_destinations`, `human_transfer_mode`, `warm_transfer_summary_instructions`, `warm_transfer_voice_speed`.

#### `revox_get_calls`

Search/list calls

Arguments: `query`, `statuses`, `directions`, `results`, `outcomes`, `assistant_ids`, `campaign_ids`, `from_phone_numbers`, `assignee_ids`, `variables`, `to_phone_number`, `call_ids`, `page`, `page_size`, `sort_by`, `sort_direction`.

#### `revox_list_assistants`

Get all assistants for the organization. Each comes with its dashboard_url and test_url (opens the page with the web test call ready).

#### `revox_get_assistant`

Get an assistant by ID, with its dashboard_url and test_url (opens the page with the web test call ready).

Arguments: `id`.

#### `revox_get_prompt_guide`

Revox's prompt-creation guide (in French): the rules for an assistant's prompt on a phone call (identity and opener, personalization with variables, turns, qualification, objections, transfers and bookings, end of call) and the checks before delivering it. You MUST call this before revox_create_assistant, and before revox_update_assistant changes prompt or first_sentence, then write the prompt following it. It returns a guide_version to pass as prompt_guide_version. Pass the paths matching the case to also get their examples.

Arguments: `paths`.

#### `revox_create_assistant`

Create a new assistant. You MUST call revox_get_prompt_guide first and write the prompt following it; pass its guide_version as prompt_guide_version. Set voice_provider and voice_id for a specific accent (e.g. French): let the user choose by ear with revox_pick_voice, or use revox_list_voices and pick a voice whose language matches your prompt. custom_tools are HTTP endpoints the agent can call during the conversation; webhook_url receives each call's report when it ends; precall_lookup_url (inbound calls) is queried before answering to fill the prompt variables. To transfer calls to a human, set transfer_destinations (label + E.164 number each) and human_transfer_mode (warm: the AI briefs the colleague before connecting, the default; cold: direct SIP transfer); the prompt must say when to transfer and, with several destinations, which label to pick. post_call_prompt sets what happens once the call has ended (emails, SMS, Slack or Teams messages, CRM): read its description for how to write it and which tools exist. To text the person during the call instead, write in the prompt when to use @send_sms (only works when the number can receive SMS). For the assistant to book meetings, add its calendars with revox_connect_calendar. revox_list_assistant_tools lists everything its prompts can mention as @name, including those calendars. The result carries the assistant's dashboard_url and test_url: give the user test_url so they can talk to the assistant right away in their browser (web test call).

Arguments: `prompt_guide_version`, `name`, `prompt`, `first_sentence`, `first_sentence_mode`, `end_of_call_sentence`, `voicemail_message`, `max_call_duration_secs`, `structured_output_config`, `structured_output_prompt`, `webhook_url`, `custom_tools`, `post_call_prompt`, `transfer_destinations`, `human_transfer_mode`, `warm_transfer_summary_instructions`, `warm_transfer_voice_speed`, `precall_lookup_url`, `precall_lookup_headers`, `voice_provider`, `voice_id`, `voice_speed`, `voice_volume`, `voice_model`.

#### `revox_update_assistant`

Update an assistant by ID. Only the fields you pass change. To change prompt or first_sentence, you MUST call revox_get_prompt_guide first, rework the text following it, and pass its guide_version as prompt_guide_version. Include voice_provider and voice_id to change the voice (e.g. to a French accent). custom_tools replaces the whole list (null removes them all); precall_lookup_url and precall_lookup_headers take null to remove the inbound lookup. To transfer calls to a human, set transfer_destinations (label + E.164 number each) and human_transfer_mode (warm: the AI briefs the colleague before connecting, the default; cold: direct SIP transfer); the prompt must say when to transfer and, with several destinations, which label to pick. transfer_destinations: null removes the transfer. post_call_prompt sets what happens once the call has ended (emails, SMS, Slack or Teams messages, CRM): read its description for how to write it and which tools exist. To text the person during the call instead, write in the prompt when to use @send_sms (only works when the number can receive SMS). For the assistant to book meetings, add its calendars with revox_connect_calendar. revox_list_assistant_tools lists everything its prompts can mention as @name, including those calendars. The result carries the assistant's dashboard_url and test_url: give the user test_url so they can talk to the assistant right away in their browser (web test call).

Arguments: `id`, `prompt_guide_version`, `name`, `prompt`, `first_sentence`, `first_sentence_mode`, `end_of_call_sentence`, `voicemail_message`, `max_call_duration_secs`, `structured_output_config`, `structured_output_prompt`, `webhook_url`, `custom_tools`, `post_call_prompt`, `transfer_destinations`, `human_transfer_mode`, `warm_transfer_summary_instructions`, `warm_transfer_voice_speed`, `precall_lookup_url`, `precall_lookup_headers`, `voice_provider`, `voice_id`, `voice_speed`, `voice_volume`, `voice_model`.

#### `revox_check_assistant_setup`

Check a saved assistant for the setup mistakes that break real calls (persona gender vs voice, transfer or booking with nothing connected, leftover template text, wrong language, wording that reads wrong once variables are filled). Call it once after your last revox_create_assistant or revox_update_assistant, not after each edit: a fresh check takes a few seconds. Apply each issue's fix with revox_update_assistant (a text fix replaces `find` with `replace` in `field`; a voice fix switches to `voice`), then check again. An empty list means nothing major was found.

Arguments: `id`, `locale`.

#### `revox_list_voices`

Get available voices (Cartesia, ElevenLabs, Inworld).

#### `revox_get_voice`

Get a voice by ID and provider.

Arguments: `id`, `provider`.

#### `revox_pick_voice`

You cannot play audio, so let the user listen and choose: this returns a url to a Revox page where they audition voices and validate one. Give the user the url (ask them to open it and validate a voice), then call revox_wait_for_voice_pick with the pick_id: it returns the voice once validated, as voice_provider, voice_id, voice_speed, voice_volume and voice_model, to pass to revox_create_assistant or revox_update_assistant. Prefer this over choosing from revox_list_voices whenever the user cares about the voice.

Arguments: `language`, `purpose`.

#### `revox_wait_for_voice_pick`

Wait until the user validates a voice on the revox_pick_voice page, or the server time window expires (~240 s). If the result contains `_retry: true`, the user has not chosen yet: call this tool again with the same pick_id (or ask them where they are). Once chosen, it returns immediately with the voice; the user can validate another one on the same page, and calling this again returns the latest.

Arguments: `pick_id`.

#### `revox_list_assistant_tools`

Everything an assistant's prompts can name as @name: call_tools for its prompt (the built-in actions, its calendars under their generated handles, its custom tools), post_call_tools for its post_call_prompt. Each has its mention, a description, an example, and whether it is available on this assistant, with the setup it lacks otherwise. A calendar appears once an account is connected to it. Call this before writing a prompt that uses them.

Arguments: `assistant_id`.

#### `revox_list_calendars`

The calendars an assistant books meetings on: their status (not_connected, needs_setup, ready), the mention the prompt uses, the connected account, the settings, and the link to connect them (invite.url) with what to do next.

Arguments: `assistant_id`.

#### `revox_connect_calendar`

You cannot sign in to a calendar account, so the user does: this returns a url to a Revox page where they (or a colleague, no Revox account needed) connect their Google Calendar, Calendly or Cal.com account and pick what to book on. Pass provider to add a new calendar to the assistant, or calendar_id for a new link to one with no account (the previous link stops working). Anyone holding the link can connect an account, so give it only to the person concerned. Give the user the url, then call revox_wait_for_calendar. An assistant can have several calendars: call this once per calendar.

Arguments: `assistant_id`, `provider`, `calendar_id`.

#### `revox_wait_for_calendar`

Wait until the calendar from revox_connect_calendar is ready to take bookings, or the server time window expires (~240 s). If the result contains `_retry: true`, it is not ready yet: follow its next_step, then call this tool again with the same ids (or ask the user where they are). Once ready, it returns the calendar with its mention, the @handle generated from the connected account.

Arguments: `assistant_id`, `calendar_id`.

#### `revox_get_calendar_options`

The calendars (Google) or event types (Calendly, Cal.com) of the connected account, to pass one to revox_select_calendar_option. A notice says when the account's plan will stop bookings: tell the user. An option with bookable false is a Google calendar shared read-only: it cannot be picked, so if it is the one the user wants, tell them to ask its owner for "Make changes to events".

Arguments: `assistant_id`, `calendar_id`.

#### `revox_select_calendar_option`

Pick the calendar or event type of the connected account, with an id from revox_get_calendar_options.

Arguments: `assistant_id`, `calendar_id`, `option_id`.

#### `revox_update_calendar_settings`

Google Calendar: opening hours, meeting length and Meet link. Calendly and Cal.com: the event type. Settings replace the current ones as a whole and must match the calendar's provider: start from connection.settings in revox_list_calendars. The calendar must have an account connected.

Arguments: `assistant_id`, `calendar_id`, `settings`.

#### `revox_disconnect_calendar`

The calendar keeps its handle, which the agent treats as not available, and its link is revoked. Use revox_connect_calendar with its calendar_id to connect another account, which gives it that account's handle: update the prompt if it mentions the old one. Ask the user first.

Arguments: `assistant_id`, `calendar_id`.

#### `revox_remove_calendar`

The agent stops booking on it. The account connection is deleted too, unless another calendar still uses it. Update the prompt if it mentions this calendar. Ask the user first.

Arguments: `assistant_id`, `calendar_id`.

#### `revox_get_current_user`

Get the authenticated user.

#### `revox_list_campaigns`

Get all campaigns for the organization.

#### `revox_get_balance`

Get organization balance (in euro cents).

---

## Webhooks

When an assistant has a `webhook_url`, Revox sends an HTTP `POST` with a JSON body to that URL after its calls. Set it with [POST /assistants](/docs/api/assistants/create-an-assistant) or [PATCH /assistants/{id}](/docs/api/assistants/update-an-assistant).

- Answer with a `2xx` status quickly, then do the work asynchronously.
- Requests are not signed. To make sure a request comes from Revox, put a secret token in the URL (`https://example.com/revox-webhook?token=...`) and check it, or fetch the call again with [GET /call/{id}](/docs/api/calls/get-call-by-id) before acting on it.
- The `call` in the payload is the same object [GET /call/{id}](/docs/api/calls/get-call-by-id) returns.

### Payload

Webhook called when a call is completed.

- `call` ([Call](https://www.getrevox.com/docs/api/objects/call.md), required)
- `call_attempt` ([CallAttempt](https://www.getrevox.com/docs/api/objects/call-attempt.md), required)
- `assistant` (object, required, nullable)
  - `id` (string, required)
  - `type` (enum (string), required): One of: `standalone`, `multi-step`, `sub-assistant`.
  - `position` (object, required, nullable)
    - `x` (number, required)
    - `y` (number, required)
  - `start_step_name` (string, required, nullable)
  - `prompt` (string, required)
  - `post_call_prompt` (string, required, nullable)
  - `first_sentence` (string, required, nullable)
  - `first_sentence_mode` (enum (string), required): One of: `generated`, `static`, `none`.
  - `end_of_call_sentence` (string, required, nullable)
  - `voice` (object, required, nullable)
    - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
    - `id` (string, required): The ID of the voice. Constraints: min length 1.
    - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
    - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
    - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
  - `voice_languages` (array of object, required, nullable): Extra languages for a multilingual assistant, each with its own voice. Null for a single-language assistant.
    - `language` (enum (string), required): The language contacts are called in with this voice. One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.
    - `voice` (object, required): The voice used for contacts whose language is this language.
      - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
      - `id` (string, required): The ID of the voice. Constraints: min length 1.
      - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
      - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
      - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
  - `cartesia_dictionary_pronunciation_id` (string, required, nullable): Optional Cartesia pronunciation dictionary ID linked to this assistant.
  - `llm_model` (one of, required)
    - One of, **Recommended** (object)
      - `type` (string (constant), required): The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.
    - One of, **Gpt41Priority** (object)
      - `type` (string (constant), required): OpenAI gpt-4.1 on the priority tier, with gpt-4.1-mini answering a turn when gpt-4.1 is slow to respond. No per-assistant configuration.
    - One of, **Realtime** (object)
      - `type` (string (constant), required): Use a model from Realtime.
      - `provider` (enum (string), required): The provider to use from Realtime. eg: openai, google. One of: `openai`, `google`.
      - `realtime_model_id` (string, required): The model ID to use from Realtime. eg: gpt-4.1
      - `realtime_voice_id` (string, optional): Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck). Constraints: min length 1.
  - `webhook_url` (string, required, nullable): The webhook URL to call when the call is completed.
  - `max_call_duration_secs` (number, required): The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.
  - `max_duration_end_message` (string, required, nullable): Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If null, the call ends silently. Constraints: max length 150.
  - `structured_output_config` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required, nullable): The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).
  - `structured_output_prompt` (string, required, nullable): Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
  - `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), required, nullable): Configuration for call retry behavior including time windows, delays, and max iterations.
  - `background_sound` (enum (string), required, nullable): Ambient background sound to play during the call. null disables it. One of: `audio/office.ogg`, `audio/waves.m4a`.
  - `background_sound_volume` (number, required): Volume of the ambient background sound (0 = silent, 1 = max). Constraints: min 0, max 1.
  - `thinking_sound` (enum (string), required, nullable): Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null disables it. One of: `city-ambience.ogg`, `forest-ambience.ogg`, `office-ambience.ogg`, `crowded-room.ogg`, `keyboard-typing.ogg`, `keyboard-typing2.ogg`, `hold_music.ogg`.
  - `thinking_sound_volume` (number, required): Volume of the thinking sound (0 = silent, 1 = max). Constraints: min 0, max 1.
  - `thinking_sound_probability` (number, required): Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking. Constraints: min 0, max 1.
  - `transfer_destinations` (array of object, required, nullable): Where calls can be transferred to when users ask to speak to a human. Null or empty when transfer is not configured.
    - `label` (string, required): Constraints: min length 1, max length 60.
    - `phone_number` (string, required)
  - `human_transfer_mode` (enum (string), required, nullable): Warm or cold transfer when transfer_destinations is non-empty; null when transfer is not configured. One of: `warm`, `cold`.
  - `warm_transfer_summary_instructions` (string, required, nullable): Warm transfer only: instructions for the supervisor handoff summary; null when not configured or cold transfer.
  - `warm_transfer_voice_speed` (number, required, nullable): Warm transfer only: voice speed of the briefing to the human colleague; null when it follows voice.speed, not configured, or cold transfer. Constraints: min 0.6, max 1.5.
  - `ivr_navigation_enabled` (boolean, required): Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.
  - `voicemail_message` (string, required, nullable): If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.
  - `stt_context` (object, required, nullable): Assistant-level speech-to-text context: structured `general` key/value pairs plus a list of domain `terms`. Prompt-derived context is merged in without replacing existing entries.
    - `general` (array of object, required): Default: `[]`.
      - `key` (string, required): Constraints: min length 1.
      - `value` (string, required): Constraints: min length 1.
    - `terms` (array of string, required): Default: `[]`.
  - `stt_model` (enum (string), required): Transcriber (speech-to-text) model used for the assistant. One of: `stt-rt-v4`, `stt-rt-v5`.
  - `stt_endpoint_sensitivity` (number, required, nullable): Soniox endpoint sensitivity override (-1 to 1). Null: the agent's default tuning.
  - `stt_endpoint_latency_level` (integer, required, nullable): Soniox endpoint latency adjustment level override (0 to 3). Null: the agent's default tuning. Constraints: min -9007199254740991, max 9007199254740991.
  - `stt_bvc_filter_enabled` (boolean, required): When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output.
  - `krisp_viva_filter_enabled` (boolean, required): When true, the agent's noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony.
  - `first_sentence_delay_ms` (integer, required): Delay in milliseconds before speaking the first sentence. Default: 400. Constraints: min -9007199254740991, max 9007199254740991.
  - `calendars` (array of [AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required): The calendars the agent books meetings on during a call, each named by the handle the prompt mentions. Only the `ready` ones are offered to the agent.
  - `calendly` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
    - `connection_id` (string, required): The connection ID representing the link between your Calendly account and Revox.
    - `event_type_id` (string, required): The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5) Constraints: min length 1.
  - `cal` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
    - `connection_id` (string, required): The connection ID representing the link between your Cal.com account and Revox.
    - `event_type_id` (string, required): The Cal.com event type to schedule. (eg: 7081322) Constraints: min length 1.
  - `google_calendar` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
    - `calendar_id` (string, required): The Google calendar to book on. (eg: primary)
    - `time_zone` (string, required): The timezone of the opening hours. (eg: Europe/Paris)
    - `duration_minutes` (integer, required): Constraints: min 5, max 480. Default: `30`.
    - `days` (array of integer, required): The open days, 0 is Sunday. Default: `[1,2,3,4,5]`.
    - `start_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"09:00"`.
    - `end_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"18:00"`.
    - `google_meet` (boolean, required): Adds a Google Meet link to the meeting. Default: `true`.
    - `connection_id` (string, required): The connection ID representing the link between your Google account and Revox.
  - `hubspot` (object, required, nullable)
    - `connection_id` (string, required): The Nango connection ID linking the org's HubSpot account to Revox.
    - `precall_lookup_enabled` (boolean, required): Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up. Default: `false`.
    - `meeting_links` (array of object, required): Scheduling pages the agent can book on during a call — typically one per sales rep plus a round-robin team page marked as the fallback. Default: `[]`.
      - `slug` (string, required): HubSpot scheduling page slug, as returned by the meeting-links API (e.g. 'julien-marchand'). Constraints: min length 1.
      - `label` (string, required): Name the agent recognises for this calendar (e.g. 'Julien Marchand'). Listed in the prompt and matched against what the caller asks for. Constraints: min length 1.
      - `duration_ms` (integer, required): Meeting duration in milliseconds, chosen among the durations the scheduling page offers (e.g. 1800000 for 30 minutes). Constraints: max 9007199254740991, > 0.
      - `is_fallback` (boolean, required): Marks the round-robin calendar the agent falls back to when the requested rep has no slot. At most one meeting link may set this.
      - `booking_url` (string, required, nullable): Public URL of the scheduling page (e.g. https://meetings-eu1.hubspot.com/julien). The agent books through the API and only texts this link to the caller when the booking fails and the call can receive an SMS. Null on calendars saved before this field existed. Default: `null`.
    - `post_call_sync` (object, optional): Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.
      - `enabled` (boolean, required): Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says. Default: `false`.
      - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties. Default: `[]`.
        - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
        - `hubspot_property` (string, required): Destination HubSpot contact property, by internal name (e.g. 'email', 'company', or a custom 'budget'). Constraints: min length 1.
  - `slack` (object, required, nullable)
    - `connection_id` (string, required): The Nango connection ID linking the org's Slack workspace to Revox.
    - `channels` (array of object, required): The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
      - `id` (string, required): The Slack channel ID (e.g. 'C01234567').
      - `name` (string, optional, nullable): Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
  - `teams` (object, required, nullable)
    - `connection_id` (string, required): The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.
    - `channels` (array of object, required): The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
      - `id` (string, required): The Microsoft Teams channel ID (e.g. '19:561fbdbb...@thread.tacv2').
      - `name` (string, optional, nullable): Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
      - `team_id` (string, required): The ID of the team the channel belongs to. Needed to post.
      - `team_name` (string, optional, nullable): Human-readable team name. Channel names repeat across teams (every team has a 'General'), so the team name is what tells two of them apart.
  - `zoho` (object, required, nullable)
    - `connection_id` (string, required): The Nango connection ID linking the org's Zoho CRM account to Revox.
    - `module` (string, required): Zoho module the prospect record is upserted into (e.g. 'Leads' or 'Contacts'). Constraints: min length 1.
    - `log_call_activity` (boolean, required): When true, also log the call as a record in Zoho's Calls module (related to the upserted prospect via Who_Id).
    - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.
      - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
      - `zoho_field` (string, required): Destination Zoho field API name on the upserted record (e.g. 'Email', 'Company', or a custom 'Budget__c'). Constraints: min length 1.
    - `template` (string, optional, nullable): Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.
  - `custom_tools` (array of object, required, nullable)
    - `name` (string, required): Unique tool name in lowercase_snake_case (e.g. check_inventory) Constraints: min length 1, pattern ^[a-z][a-z0-9_]*$.
    - `description` (string, required): Human-readable description of what the tool does, used by the LLM to decide when to call it Constraints: min length 1.
    - `method` (enum (string), required): HTTP method to use when calling the API endpoint One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
    - `url` (string, required): Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values Constraints: min length 1.
    - `headers` (array of object, required): HTTP headers to include in the request. Values support {{variable}} placeholders Default: `[]`.
      - `key` (string, required): Constraints: min length 1.
      - `value` (string, required)
    - `query_params` (array of object, required): Query string parameters appended to the URL. Values support {{variable}} placeholders Default: `[]`.
      - `key` (string, required): Constraints: min length 1.
      - `value` (string, required)
    - `body_template` (string, required, nullable): JSON body template for the request. Use quoted {{variable}} placeholders (e.g. "{{name}}") for dynamic values Default: `null`.
    - `input_schema` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required): Schema defining the parameters the LLM should extract from the conversation to pass to this tool
  - `from_phone_number` (string, required, nullable): Override the default outbound phone number for calls placed with this assistant. When null, the organization's default phone number is used.
  - `logo_url` (string, required, nullable): Public URL of the brand logo shown on the assistant's demo page. Null when unset.
  - `precall_lookup_url` (string, required, nullable): URL fetched before an inbound call is answered to resolve the assistant's prompt variables. Null when no lookup is configured.
  - `precall_lookup_headers` (array of object, required, nullable): HTTP headers sent with the pre-call lookup request. Null when none are configured.
    - `key` (string, required): Constraints: max length 200, pattern ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$.
    - `value` (string, required): Constraints: min length 1, max length 4000.

---

## GET /auth-status

`GET https://www.getrevox.com/api/auth-status`

Check if your API key is still valid.

### Example request

```bash
curl -X GET https://www.getrevox.com/api/auth-status \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `authenticated` (boolean, required): True if the API key is still valid.

#### 401: Missing or invalid API key

- `error` (string, required)

---

## Get assistants

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

Retrieve all assistants associated with your account. Each assistant in the response includes its full configuration: prompt, voice settings, and first sentence. Use this endpoint to list available assistants before placing calls.

### Example request

```bash
curl -X GET https://www.getrevox.com/api/assistants \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `assistants` (array of [Assistant](https://www.getrevox.com/docs/api/objects/assistant.md), required)

---

## Create an assistant

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

Create a new AI assistant with a custom prompt, voice, and behavior configuration. Assistants define how the AI agent behaves during calls, including the system prompt given to the LLM, the first sentence spoken, the voice provider and voice ID (Cartesia or ElevenLabs), and end-of-call behavior. Once created, reference the assistant by its ID when placing calls.

### Request body (JSON)

- `type` (enum (string), optional): Assistant kind. 'standalone' (default) is a normal assistant, 'multi-step' orchestrates a flow of sub-assistants, 'sub-assistant' is a step inside a multi-step flow (hidden from the assistants list). Flow transitions are managed via the /assistants/:id/edges endpoints, not on the assistant itself. One of: `standalone`, `multi-step`, `sub-assistant`.
- `position` (object, optional, nullable): Canvas position of this assistant's node in its multi-step flow editor.
  - `x` (number, required)
  - `y` (number, required)
- `start_step_name` (string, optional, nullable): Name of a multi-step flow's start step. Defaults to the assistant's name. Constraints: max length 255.
- `prompt` (string, required): The prompt to use for the call. This will be given to the LLM (gpt-4.1)
- `post_call_prompt` (string, optional, nullable): Instructions the agent follows once the call has ended: who to email, when to text, what to post on Slack or Teams. Plain language, no template syntax. Empty or null means no post-call agent runs.
- `first_sentence` (string, optional): The first sentence to use for the call. This will be given to the LLM
- `first_sentence_mode` (enum (string), optional): How the first sentence should be handled. "generated" means the LLM will generate a response based on the first_sentence instruction. "static" means the first_sentence will be spoken exactly as provided. "none" means the agent will not speak first and will wait for the user. One of: `generated`, `static`, `none`.
- `end_of_call_sentence` (string, optional): Optional message to say when the agent decides to end the call.
- `voice` (object, optional): The voice to use for the call. You can get the list of voices using the /voices endpoint
  - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
  - `id` (string, required): The ID of the voice. Constraints: min length 1.
  - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
  - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
  - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
- `voice_languages` (array of object, optional, nullable): Extra languages for a multilingual assistant, each with its own voice (any provider). A call picks one with a `language` entry in its prompt_variables (a language code such as "es", or a name such as "Spanish"); otherwise the phone number's country picks one, and failing that the call runs in the language of `voice`, which cannot be listed here. A changed voice is applied to the calls in that language that have not completed yet; a language still used by such a call cannot be removed.
  - `language` (enum (string), required): The language contacts are called in with this voice. One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.
  - `voice` (object, required): The voice used for contacts whose language is this language.
    - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
    - `id` (string, required): The ID of the voice. Constraints: min length 1.
    - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
    - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
    - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
- `cartesia_dictionary_pronunciation_id` (string, optional, nullable): Optional Cartesia pronunciation dictionary ID to use for this assistant's calls. Set null to unlink it. Constraints: min length 1.
- `llm_model` (one of, optional)
  - One of, **Recommended** (object)
    - `type` (string (constant), required): The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.
  - One of, **Gpt41Priority** (object)
    - `type` (string (constant), required): OpenAI gpt-4.1 on the priority tier, with gpt-4.1-mini answering a turn when gpt-4.1 is slow to respond. No per-assistant configuration.
  - One of, **Realtime** (object)
    - `type` (string (constant), required): Use a model from Realtime.
    - `provider` (enum (string), required): The provider to use from Realtime. eg: openai, google. One of: `openai`, `google`.
    - `realtime_model_id` (string, required): The model ID to use from Realtime. eg: gpt-4.1
    - `realtime_voice_id` (string, optional): Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck). Constraints: min length 1.
- `webhook_url` (string, optional): The webhook URL to call when the call is completed.
- `max_call_duration_secs` (number, optional): The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.
- `max_duration_end_message` (string, optional, nullable): Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If not set, the call ends silently. Constraints: max length 150.
- `structured_output_config` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), optional): The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).
- `structured_output_prompt` (string, optional, nullable): Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
- `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), optional)
- `background_sound` (enum (string), optional, nullable): Ambient background sound to play during the call. null/omitted disables it. One of: `audio/office.ogg`, `audio/waves.m4a`.
- `background_sound_volume` (number, optional): Volume of the ambient background sound (0 = silent, 1 = max). Constraints: min 0, max 1.
- `thinking_sound` (enum (string), optional, nullable): Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null/omitted disables it. One of: `city-ambience.ogg`, `forest-ambience.ogg`, `office-ambience.ogg`, `crowded-room.ogg`, `keyboard-typing.ogg`, `keyboard-typing2.ogg`, `hold_music.ogg`.
- `thinking_sound_volume` (number, optional): Volume of the thinking sound (0 = silent, 1 = max). Constraints: min 0, max 1.
- `thinking_sound_probability` (number, optional): Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking. Constraints: min 0, max 1.
- `transfer_destinations` (array of object, optional, nullable): Where calls can be transferred to when users ask to speak to a human. With a single entry the assistant always transfers there; with several, it picks one at transfer time by applying the routing rules written in the assistant's own prompt (which refer to the destination labels). Empty or null disables transfer.
  - `label` (string, required): Human-meaningful name for this destination (e.g. "Sales"). The assistant's prompt refers to these labels when describing who to transfer to. Constraints: min length 1, max length 60.
  - `phone_number` (string, required): Destination phone number in E.164 format (e.g. +1234567890).
- `human_transfer_mode` (enum (string), optional, nullable): When transfer_destinations is non-empty: "warm" (AI bridges) or "cold" (SIP REFER; trunk must allow REFER/PSTN). Omit or null when transfer is disabled. One of: `warm`, `cold`.
- `warm_transfer_summary_instructions` (string, optional, nullable): When using warm transfer: extra instructions for the supervisor handoff summary. If null or empty, the API uses the product default briefing when the call is loaded for the agent.
- `warm_transfer_voice_speed` (number, optional, nullable): When using warm transfer: voice speed used only while the AI briefs the human colleague. Same range as voice.speed. Omit or null to brief at the assistant's voice speed. Constraints: min 0.6, max 1.5.
- `ivr_navigation_enabled` (boolean, optional): Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.
- `voicemail_message` (string, optional, nullable): If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately. Left on the first attempt only (second dial of a double call). Takes the same {{variables}} as the prompt (e.g. "Hi {{first_name}}, this is Julie from Acme, please call us back.").
- `stt_context` (object, optional, nullable): Assistant-level speech-to-text context: structured `general` key/value pairs plus a list of domain `terms`. Prompt-derived context is merged in without replacing existing entries.
  - `general` (array of object, required): Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required): Constraints: min length 1.
  - `terms` (array of string, required): Default: `[]`.
- `stt_model` (enum (string), optional): Transcriber (speech-to-text) model. Defaults to the newest Soniox realtime model when omitted. One of: `stt-rt-v4`, `stt-rt-v5`.
- `stt_endpoint_sensitivity` (number, optional, nullable): Soniox endpoint sensitivity override (-1 to 1). Higher values finalize transcripts sooner. Null or omitted: the agent's default tuning. Constraints: min -1, max 1.
- `stt_endpoint_latency_level` (integer, optional, nullable): Soniox endpoint latency adjustment level override (0 to 3). Higher values reduce endpoint latency at a slight accuracy cost. Null or omitted: the agent's default tuning. Constraints: min 0, max 3.
- `stt_bvc_filter_enabled` (boolean, optional): When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output. Default true.
- `krisp_viva_filter_enabled` (boolean, optional): When true, the agent's noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony. Default false.
- `first_sentence_delay_ms` (integer, optional): Delay in milliseconds before speaking the first sentence. Default: 400. Constraints: min 0, max 9007199254740991.
- `calendly` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `connection_id` (string, required): The connection ID representing the link between your Calendly account and Revox.
  - `event_type_id` (string, required): The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5) Constraints: min length 1.
- `cal` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `connection_id` (string, required): The connection ID representing the link between your Cal.com account and Revox.
  - `event_type_id` (string, required): The Cal.com event type to schedule. (eg: 7081322) Constraints: min length 1.
- `google_calendar` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `calendar_id` (string, required): The Google calendar to book on. (eg: primary)
  - `time_zone` (string, required): The timezone of the opening hours. (eg: Europe/Paris)
  - `duration_minutes` (integer, required): Constraints: min 5, max 480. Default: `30`.
  - `days` (array of integer, required): The open days, 0 is Sunday. Default: `[1,2,3,4,5]`.
  - `start_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"09:00"`.
  - `end_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"18:00"`.
  - `google_meet` (boolean, required): Adds a Google Meet link to the meeting. Default: `true`.
  - `connection_id` (string, required): The connection ID representing the link between your Google account and Revox.
- `hubspot` (object, optional, nullable): HubSpot Meetings config. When set with at least one meeting link, the agent can read a rep's real availability and book the meeting natively in HubSpot during the call.
  - `connection_id` (string, required): The Nango connection ID linking the org's HubSpot account to Revox.
  - `precall_lookup_enabled` (boolean, required): Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up. Default: `false`.
  - `meeting_links` (array of object, required): Scheduling pages the agent can book on during a call — typically one per sales rep plus a round-robin team page marked as the fallback. Default: `[]`.
    - `slug` (string, required): HubSpot scheduling page slug, as returned by the meeting-links API (e.g. 'julien-marchand'). Constraints: min length 1.
    - `label` (string, required): Name the agent recognises for this calendar (e.g. 'Julien Marchand'). Listed in the prompt and matched against what the caller asks for. Constraints: min length 1.
    - `duration_ms` (integer, required): Meeting duration in milliseconds, chosen among the durations the scheduling page offers (e.g. 1800000 for 30 minutes). Constraints: max 9007199254740991, > 0.
    - `is_fallback` (boolean, required): Marks the round-robin calendar the agent falls back to when the requested rep has no slot. At most one meeting link may set this.
    - `booking_url` (string, required, nullable): Public URL of the scheduling page (e.g. https://meetings-eu1.hubspot.com/julien). The agent books through the API and only texts this link to the caller when the booking fails and the call can receive an SMS. Null on calendars saved before this field existed. Default: `null`.
  - `post_call_sync` (object, optional): Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.
    - `enabled` (boolean, required): Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says. Default: `false`.
    - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties. Default: `[]`.
      - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
      - `hubspot_property` (string, required): Destination HubSpot contact property, by internal name (e.g. 'email', 'company', or a custom 'budget'). Constraints: min length 1.
- `slack` (object, optional, nullable): Slack notification config. When set, posts a message to the chosen channel after a call ends with one of the configured outcomes.
  - `connection_id` (string, required): The Nango connection ID linking the org's Slack workspace to Revox.
  - `channels` (array of object, required): The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
    - `id` (string, required): The Slack channel ID (e.g. 'C01234567').
    - `name` (string, optional, nullable): Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
- `teams` (object, optional, nullable): Microsoft Teams config. When set with at least one channel, the post-call agent can post to those channels when the post-call instructions ask for it.
  - `connection_id` (string, required): The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.
  - `channels` (array of object, required): The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
    - `id` (string, required): The Microsoft Teams channel ID (e.g. '19:561fbdbb...@thread.tacv2').
    - `name` (string, optional, nullable): Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
    - `team_id` (string, required): The ID of the team the channel belongs to. Needed to post.
    - `team_name` (string, optional, nullable): Human-readable team name. Channel names repeat across teams (every team has a 'General'), so the team name is what tells two of them apart.
- `zoho` (object, optional, nullable): Zoho CRM integration config. When set, upserts the prospect (keyed on phone) into the chosen module and attaches a Note with the call summary after a call ends with one of the configured outcomes.
  - `connection_id` (string, required): The Nango connection ID linking the org's Zoho CRM account to Revox.
  - `module` (string, required): Zoho module the prospect record is upserted into (e.g. 'Leads' or 'Contacts'). Constraints: min length 1.
  - `log_call_activity` (boolean, required): When true, also log the call as a record in Zoho's Calls module (related to the upserted prospect via Who_Id).
  - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.
    - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
    - `zoho_field` (string, required): Destination Zoho field API name on the upserted record (e.g. 'Email', 'Company', or a custom 'Budget__c'). Constraints: min length 1.
  - `template` (string, optional, nullable): Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.
- `custom_tools` (array of object, optional, nullable): Custom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution.
  - `name` (string, required): Unique tool name in lowercase_snake_case (e.g. check_inventory) Constraints: min length 1, pattern ^[a-z][a-z0-9_]*$.
  - `description` (string, required): Human-readable description of what the tool does, used by the LLM to decide when to call it Constraints: min length 1.
  - `method` (enum (string), required): HTTP method to use when calling the API endpoint One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
  - `url` (string, required): Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values Constraints: min length 1.
  - `headers` (array of object, required): HTTP headers to include in the request. Values support {{variable}} placeholders Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required)
  - `query_params` (array of object, required): Query string parameters appended to the URL. Values support {{variable}} placeholders Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required)
  - `body_template` (string, required, nullable): JSON body template for the request. Use quoted {{variable}} placeholders (e.g. "{{name}}") for dynamic values Default: `null`.
  - `input_schema` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required): Schema defining the parameters the LLM should extract from the conversation to pass to this tool
- `from_phone_number` (string, optional, nullable): Override the default outbound phone number for calls placed with this assistant. Must be a phone number owned by the organization in E.164 format (e.g. +1234567890). When null, the organization's default phone number is used.
- `logo_url` (string (uri), optional, nullable): Public URL of the brand logo shown on the assistant's demo page. Upload a new logo via POST /assistants/:id/logo. Set explicitly to null to clear it.
- `precall_lookup_url` (string, optional, nullable): Inbound calls only. URL fetched over HTTP GET right before the call is answered, with `{{phone}}` replaced by the caller's number in E.164 format (URL-encoded), to fill the `{{variable}}` placeholders the assistant declares. It answers either `{"prompt_variables": {...}}` or a flat JSON object whose top-level fields are the variables. The call is always answered: if the endpoint fails, takes more than 3 seconds, answers 404 or leaves a variable out, the missing variables are marked as not provided. Must be an http(s) URL containing `{{phone}}`. When null, no lookup is performed. Constraints: max length 2000.
- `precall_lookup_headers` (array of object, optional, nullable): HTTP headers sent with the pre-call lookup request, e.g. an API key. Null or empty when the endpoint needs none.
  - `key` (string, required): Constraints: max length 200, pattern ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$.
  - `value` (string, required): Constraints: min length 1, max length 4000.
- `name` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/assistants \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are Julie from Acme. You call to confirm tomorrow'\''s appointment.",
    "name": "Appointment reminder"
  }'
```

### Responses

#### 200: Success

- `assistant` ([Assistant](https://www.getrevox.com/docs/api/objects/assistant.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Get assistant by ID

`GET https://www.getrevox.com/api/assistants/{id}`

Retrieve a single assistant by its unique ID. Returns the full assistant configuration including prompt, voice settings, and first sentence mode. Useful for inspecting an assistant's current setup before updating it or placing a call.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X GET https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `id` (string, required)
- `type` (enum (string), required): One of: `standalone`, `multi-step`, `sub-assistant`.
- `position` (object, required, nullable)
  - `x` (number, required)
  - `y` (number, required)
- `start_step_name` (string, required, nullable)
- `prompt` (string, required)
- `post_call_prompt` (string, required, nullable)
- `first_sentence` (string, required, nullable)
- `first_sentence_mode` (enum (string), required): One of: `generated`, `static`, `none`.
- `end_of_call_sentence` (string, required, nullable)
- `voice` (object, required, nullable)
  - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
  - `id` (string, required): The ID of the voice. Constraints: min length 1.
  - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
  - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
  - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
- `voice_languages` (array of object, required, nullable): Extra languages for a multilingual assistant, each with its own voice. Null for a single-language assistant.
  - `language` (enum (string), required): The language contacts are called in with this voice. One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.
  - `voice` (object, required): The voice used for contacts whose language is this language.
    - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
    - `id` (string, required): The ID of the voice. Constraints: min length 1.
    - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
    - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
    - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
- `cartesia_dictionary_pronunciation_id` (string, required, nullable): Optional Cartesia pronunciation dictionary ID linked to this assistant.
- `llm_model` (one of, required)
  - One of, **Recommended** (object)
    - `type` (string (constant), required): The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.
  - One of, **Gpt41Priority** (object)
    - `type` (string (constant), required): OpenAI gpt-4.1 on the priority tier, with gpt-4.1-mini answering a turn when gpt-4.1 is slow to respond. No per-assistant configuration.
  - One of, **Realtime** (object)
    - `type` (string (constant), required): Use a model from Realtime.
    - `provider` (enum (string), required): The provider to use from Realtime. eg: openai, google. One of: `openai`, `google`.
    - `realtime_model_id` (string, required): The model ID to use from Realtime. eg: gpt-4.1
    - `realtime_voice_id` (string, optional): Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck). Constraints: min length 1.
- `webhook_url` (string, required, nullable): The webhook URL to call when the call is completed.
- `max_call_duration_secs` (number, required): The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.
- `max_duration_end_message` (string, required, nullable): Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If null, the call ends silently. Constraints: max length 150.
- `structured_output_config` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required, nullable): The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).
- `structured_output_prompt` (string, required, nullable): Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
- `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), required, nullable): Configuration for call retry behavior including time windows, delays, and max iterations.
- `background_sound` (enum (string), required, nullable): Ambient background sound to play during the call. null disables it. One of: `audio/office.ogg`, `audio/waves.m4a`.
- `background_sound_volume` (number, required): Volume of the ambient background sound (0 = silent, 1 = max). Constraints: min 0, max 1.
- `thinking_sound` (enum (string), required, nullable): Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null disables it. One of: `city-ambience.ogg`, `forest-ambience.ogg`, `office-ambience.ogg`, `crowded-room.ogg`, `keyboard-typing.ogg`, `keyboard-typing2.ogg`, `hold_music.ogg`.
- `thinking_sound_volume` (number, required): Volume of the thinking sound (0 = silent, 1 = max). Constraints: min 0, max 1.
- `thinking_sound_probability` (number, required): Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking. Constraints: min 0, max 1.
- `transfer_destinations` (array of object, required, nullable): Where calls can be transferred to when users ask to speak to a human. Null or empty when transfer is not configured.
  - `label` (string, required): Constraints: min length 1, max length 60.
  - `phone_number` (string, required)
- `human_transfer_mode` (enum (string), required, nullable): Warm or cold transfer when transfer_destinations is non-empty; null when transfer is not configured. One of: `warm`, `cold`.
- `warm_transfer_summary_instructions` (string, required, nullable): Warm transfer only: instructions for the supervisor handoff summary; null when not configured or cold transfer.
- `warm_transfer_voice_speed` (number, required, nullable): Warm transfer only: voice speed of the briefing to the human colleague; null when it follows voice.speed, not configured, or cold transfer. Constraints: min 0.6, max 1.5.
- `ivr_navigation_enabled` (boolean, required): Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.
- `voicemail_message` (string, required, nullable): If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.
- `stt_context` (object, required, nullable): Assistant-level speech-to-text context: structured `general` key/value pairs plus a list of domain `terms`. Prompt-derived context is merged in without replacing existing entries.
  - `general` (array of object, required): Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required): Constraints: min length 1.
  - `terms` (array of string, required): Default: `[]`.
- `stt_model` (enum (string), required): Transcriber (speech-to-text) model used for the assistant. One of: `stt-rt-v4`, `stt-rt-v5`.
- `stt_endpoint_sensitivity` (number, required, nullable): Soniox endpoint sensitivity override (-1 to 1). Null: the agent's default tuning.
- `stt_endpoint_latency_level` (integer, required, nullable): Soniox endpoint latency adjustment level override (0 to 3). Null: the agent's default tuning. Constraints: min -9007199254740991, max 9007199254740991.
- `stt_bvc_filter_enabled` (boolean, required): When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output.
- `krisp_viva_filter_enabled` (boolean, required): When true, the agent's noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony.
- `first_sentence_delay_ms` (integer, required): Delay in milliseconds before speaking the first sentence. Default: 400. Constraints: min -9007199254740991, max 9007199254740991.
- `calendars` (array of [AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required): The calendars the agent books meetings on during a call, each named by the handle the prompt mentions. Only the `ready` ones are offered to the agent.
- `calendly` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `connection_id` (string, required): The connection ID representing the link between your Calendly account and Revox.
  - `event_type_id` (string, required): The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5) Constraints: min length 1.
- `cal` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `connection_id` (string, required): The connection ID representing the link between your Cal.com account and Revox.
  - `event_type_id` (string, required): The Cal.com event type to schedule. (eg: 7081322) Constraints: min length 1.
- `google_calendar` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `calendar_id` (string, required): The Google calendar to book on. (eg: primary)
  - `time_zone` (string, required): The timezone of the opening hours. (eg: Europe/Paris)
  - `duration_minutes` (integer, required): Constraints: min 5, max 480. Default: `30`.
  - `days` (array of integer, required): The open days, 0 is Sunday. Default: `[1,2,3,4,5]`.
  - `start_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"09:00"`.
  - `end_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"18:00"`.
  - `google_meet` (boolean, required): Adds a Google Meet link to the meeting. Default: `true`.
  - `connection_id` (string, required): The connection ID representing the link between your Google account and Revox.
- `hubspot` (object, required, nullable)
  - `connection_id` (string, required): The Nango connection ID linking the org's HubSpot account to Revox.
  - `precall_lookup_enabled` (boolean, required): Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up. Default: `false`.
  - `meeting_links` (array of object, required): Scheduling pages the agent can book on during a call — typically one per sales rep plus a round-robin team page marked as the fallback. Default: `[]`.
    - `slug` (string, required): HubSpot scheduling page slug, as returned by the meeting-links API (e.g. 'julien-marchand'). Constraints: min length 1.
    - `label` (string, required): Name the agent recognises for this calendar (e.g. 'Julien Marchand'). Listed in the prompt and matched against what the caller asks for. Constraints: min length 1.
    - `duration_ms` (integer, required): Meeting duration in milliseconds, chosen among the durations the scheduling page offers (e.g. 1800000 for 30 minutes). Constraints: max 9007199254740991, > 0.
    - `is_fallback` (boolean, required): Marks the round-robin calendar the agent falls back to when the requested rep has no slot. At most one meeting link may set this.
    - `booking_url` (string, required, nullable): Public URL of the scheduling page (e.g. https://meetings-eu1.hubspot.com/julien). The agent books through the API and only texts this link to the caller when the booking fails and the call can receive an SMS. Null on calendars saved before this field existed. Default: `null`.
  - `post_call_sync` (object, optional): Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.
    - `enabled` (boolean, required): Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says. Default: `false`.
    - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties. Default: `[]`.
      - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
      - `hubspot_property` (string, required): Destination HubSpot contact property, by internal name (e.g. 'email', 'company', or a custom 'budget'). Constraints: min length 1.
- `slack` (object, required, nullable)
  - `connection_id` (string, required): The Nango connection ID linking the org's Slack workspace to Revox.
  - `channels` (array of object, required): The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
    - `id` (string, required): The Slack channel ID (e.g. 'C01234567').
    - `name` (string, optional, nullable): Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
- `teams` (object, required, nullable)
  - `connection_id` (string, required): The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.
  - `channels` (array of object, required): The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
    - `id` (string, required): The Microsoft Teams channel ID (e.g. '19:561fbdbb...@thread.tacv2').
    - `name` (string, optional, nullable): Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
    - `team_id` (string, required): The ID of the team the channel belongs to. Needed to post.
    - `team_name` (string, optional, nullable): Human-readable team name. Channel names repeat across teams (every team has a 'General'), so the team name is what tells two of them apart.
- `zoho` (object, required, nullable)
  - `connection_id` (string, required): The Nango connection ID linking the org's Zoho CRM account to Revox.
  - `module` (string, required): Zoho module the prospect record is upserted into (e.g. 'Leads' or 'Contacts'). Constraints: min length 1.
  - `log_call_activity` (boolean, required): When true, also log the call as a record in Zoho's Calls module (related to the upserted prospect via Who_Id).
  - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.
    - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
    - `zoho_field` (string, required): Destination Zoho field API name on the upserted record (e.g. 'Email', 'Company', or a custom 'Budget__c'). Constraints: min length 1.
  - `template` (string, optional, nullable): Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.
- `custom_tools` (array of object, required, nullable)
  - `name` (string, required): Unique tool name in lowercase_snake_case (e.g. check_inventory) Constraints: min length 1, pattern ^[a-z][a-z0-9_]*$.
  - `description` (string, required): Human-readable description of what the tool does, used by the LLM to decide when to call it Constraints: min length 1.
  - `method` (enum (string), required): HTTP method to use when calling the API endpoint One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
  - `url` (string, required): Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values Constraints: min length 1.
  - `headers` (array of object, required): HTTP headers to include in the request. Values support {{variable}} placeholders Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required)
  - `query_params` (array of object, required): Query string parameters appended to the URL. Values support {{variable}} placeholders Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required)
  - `body_template` (string, required, nullable): JSON body template for the request. Use quoted {{variable}} placeholders (e.g. "{{name}}") for dynamic values Default: `null`.
  - `input_schema` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required): Schema defining the parameters the LLM should extract from the conversation to pass to this tool
- `from_phone_number` (string, required, nullable): Override the default outbound phone number for calls placed with this assistant. When null, the organization's default phone number is used.
- `logo_url` (string, required, nullable): Public URL of the brand logo shown on the assistant's demo page. Null when unset.
- `precall_lookup_url` (string, required, nullable): URL fetched before an inbound call is answered to resolve the assistant's prompt variables. Null when no lookup is configured.
- `precall_lookup_headers` (array of object, required, nullable): HTTP headers sent with the pre-call lookup request. Null when none are configured.
  - `key` (string, required): Constraints: max length 200, pattern ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$.
  - `value` (string, required): Constraints: min length 1, max length 4000.
- `organization_id` (string, required)
- `name` (string, required)
- `is_realestate_assistant` (boolean, optional)
- `is_inbound_receptionist` (boolean, optional)
- `created_by` (object, optional, nullable): The user who created the assistant.
  - `id` (string, required): The database user id of the creator.
  - `email` (string, required)
  - `first_name` (string, required, nullable)
  - `last_name` (string, required, nullable)
- `created_at` (any, required)
- `updated_at` (any, required)

---

## Update an assistant

`PATCH https://www.getrevox.com/api/assistants/{id}`

Update one or more fields on an existing assistant. Supports partial updates — only the fields you include in the request body will be changed. You can update the prompt, voice, first sentence, name, or any other assistant property without affecting the rest of the configuration.

### Path parameters

- `id` (string, required)

### Request body (JSON)

- `type` (enum (string), optional): Assistant kind. 'standalone' (default) is a normal assistant, 'multi-step' orchestrates a flow of sub-assistants, 'sub-assistant' is a step inside a multi-step flow (hidden from the assistants list). Flow transitions are managed via the /assistants/:id/edges endpoints, not on the assistant itself. One of: `standalone`, `multi-step`, `sub-assistant`.
- `position` (object, optional, nullable): Canvas position of this assistant's node in its multi-step flow editor.
  - `x` (number, required)
  - `y` (number, required)
- `start_step_name` (string, optional, nullable): Name of a multi-step flow's start step. Defaults to the assistant's name. Constraints: max length 255.
- `prompt` (string, optional): The prompt to use for the call. This will be given to the LLM (gpt-4.1)
- `post_call_prompt` (string, optional, nullable): Instructions the agent follows once the call has ended: who to email, when to text, what to post on Slack or Teams. Plain language, no template syntax. Empty or null means no post-call agent runs.
- `first_sentence` (string, optional): The first sentence to use for the call. This will be given to the LLM
- `first_sentence_mode` (enum (string), optional): How the first sentence should be handled. "generated" means the LLM will generate a response based on the first_sentence instruction. "static" means the first_sentence will be spoken exactly as provided. "none" means the agent will not speak first and will wait for the user. One of: `generated`, `static`, `none`.
- `end_of_call_sentence` (string, optional): Optional message to say when the agent decides to end the call.
- `voice` (object, optional): The voice to use for the call. You can get the list of voices using the /voices endpoint
  - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
  - `id` (string, required): The ID of the voice. Constraints: min length 1.
  - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
  - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
  - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
- `voice_languages` (array of object, optional, nullable): Extra languages for a multilingual assistant, each with its own voice (any provider). A call picks one with a `language` entry in its prompt_variables (a language code such as "es", or a name such as "Spanish"); otherwise the phone number's country picks one, and failing that the call runs in the language of `voice`, which cannot be listed here. A changed voice is applied to the calls in that language that have not completed yet; a language still used by such a call cannot be removed.
  - `language` (enum (string), required): The language contacts are called in with this voice. One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.
  - `voice` (object, required): The voice used for contacts whose language is this language.
    - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
    - `id` (string, required): The ID of the voice. Constraints: min length 1.
    - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
    - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
    - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
- `cartesia_dictionary_pronunciation_id` (string, optional, nullable): Optional Cartesia pronunciation dictionary ID to use for this assistant's calls. Set null to unlink it. Constraints: min length 1.
- `llm_model` (one of, optional)
  - One of, **Recommended** (object)
    - `type` (string (constant), required): The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.
  - One of, **Gpt41Priority** (object)
    - `type` (string (constant), required): OpenAI gpt-4.1 on the priority tier, with gpt-4.1-mini answering a turn when gpt-4.1 is slow to respond. No per-assistant configuration.
  - One of, **Realtime** (object)
    - `type` (string (constant), required): Use a model from Realtime.
    - `provider` (enum (string), required): The provider to use from Realtime. eg: openai, google. One of: `openai`, `google`.
    - `realtime_model_id` (string, required): The model ID to use from Realtime. eg: gpt-4.1
    - `realtime_voice_id` (string, optional): Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck). Constraints: min length 1.
- `webhook_url` (string, optional): The webhook URL to call when the call is completed.
- `max_call_duration_secs` (number, optional): The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.
- `max_duration_end_message` (string, optional, nullable): Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If not set, the call ends silently. Constraints: max length 150.
- `structured_output_config` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), optional): The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).
- `structured_output_prompt` (string, optional, nullable): Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
- `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), optional)
- `background_sound` (enum (string), optional, nullable): Ambient background sound to play during the call. null/omitted disables it. One of: `audio/office.ogg`, `audio/waves.m4a`.
- `background_sound_volume` (number, optional): Volume of the ambient background sound (0 = silent, 1 = max). Constraints: min 0, max 1.
- `thinking_sound` (enum (string), optional, nullable): Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null/omitted disables it. One of: `city-ambience.ogg`, `forest-ambience.ogg`, `office-ambience.ogg`, `crowded-room.ogg`, `keyboard-typing.ogg`, `keyboard-typing2.ogg`, `hold_music.ogg`.
- `thinking_sound_volume` (number, optional): Volume of the thinking sound (0 = silent, 1 = max). Constraints: min 0, max 1.
- `thinking_sound_probability` (number, optional): Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking. Constraints: min 0, max 1.
- `transfer_destinations` (array of object, optional, nullable): Where calls can be transferred to when users ask to speak to a human. With a single entry the assistant always transfers there; with several, it picks one at transfer time by applying the routing rules written in the assistant's own prompt (which refer to the destination labels). Empty or null disables transfer.
  - `label` (string, required): Human-meaningful name for this destination (e.g. "Sales"). The assistant's prompt refers to these labels when describing who to transfer to. Constraints: min length 1, max length 60.
  - `phone_number` (string, required): Destination phone number in E.164 format (e.g. +1234567890).
- `human_transfer_mode` (enum (string), optional, nullable): When transfer_destinations is non-empty: "warm" (AI bridges) or "cold" (SIP REFER; trunk must allow REFER/PSTN). Omit or null when transfer is disabled. One of: `warm`, `cold`.
- `warm_transfer_summary_instructions` (string, optional, nullable): When using warm transfer: extra instructions for the supervisor handoff summary. If null or empty, the API uses the product default briefing when the call is loaded for the agent.
- `warm_transfer_voice_speed` (number, optional, nullable): When using warm transfer: voice speed used only while the AI briefs the human colleague. Same range as voice.speed. Omit or null to brief at the assistant's voice speed. Constraints: min 0.6, max 1.5.
- `ivr_navigation_enabled` (boolean, optional): Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.
- `voicemail_message` (string, optional, nullable): If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately. Left on the first attempt only (second dial of a double call). Takes the same {{variables}} as the prompt (e.g. "Hi {{first_name}}, this is Julie from Acme, please call us back.").
- `stt_context` (object, optional, nullable): Assistant-level speech-to-text context: structured `general` key/value pairs plus a list of domain `terms`. Prompt-derived context is merged in without replacing existing entries.
  - `general` (array of object, required): Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required): Constraints: min length 1.
  - `terms` (array of string, required): Default: `[]`.
- `stt_model` (enum (string), optional): Transcriber (speech-to-text) model. Defaults to the newest Soniox realtime model when omitted. One of: `stt-rt-v4`, `stt-rt-v5`.
- `stt_endpoint_sensitivity` (number, optional, nullable): Soniox endpoint sensitivity override (-1 to 1). Higher values finalize transcripts sooner. Null or omitted: the agent's default tuning. Constraints: min -1, max 1.
- `stt_endpoint_latency_level` (integer, optional, nullable): Soniox endpoint latency adjustment level override (0 to 3). Higher values reduce endpoint latency at a slight accuracy cost. Null or omitted: the agent's default tuning. Constraints: min 0, max 3.
- `stt_bvc_filter_enabled` (boolean, optional): When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output. Default true.
- `krisp_viva_filter_enabled` (boolean, optional): When true, the agent's noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony. Default false.
- `first_sentence_delay_ms` (integer, optional): Delay in milliseconds before speaking the first sentence. Default: 400. Constraints: min 0, max 9007199254740991.
- `calendly` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `connection_id` (string, required): The connection ID representing the link between your Calendly account and Revox.
  - `event_type_id` (string, required): The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5) Constraints: min length 1.
- `cal` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `connection_id` (string, required): The connection ID representing the link between your Cal.com account and Revox.
  - `event_type_id` (string, required): The Cal.com event type to schedule. (eg: 7081322) Constraints: min length 1.
- `google_calendar` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `calendar_id` (string, required): The Google calendar to book on. (eg: primary)
  - `time_zone` (string, required): The timezone of the opening hours. (eg: Europe/Paris)
  - `duration_minutes` (integer, required): Constraints: min 5, max 480. Default: `30`.
  - `days` (array of integer, required): The open days, 0 is Sunday. Default: `[1,2,3,4,5]`.
  - `start_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"09:00"`.
  - `end_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"18:00"`.
  - `google_meet` (boolean, required): Adds a Google Meet link to the meeting. Default: `true`.
  - `connection_id` (string, required): The connection ID representing the link between your Google account and Revox.
- `hubspot` (object, optional, nullable): HubSpot Meetings config. When set with at least one meeting link, the agent can read a rep's real availability and book the meeting natively in HubSpot during the call.
  - `connection_id` (string, required): The Nango connection ID linking the org's HubSpot account to Revox.
  - `precall_lookup_enabled` (boolean, required): Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up. Default: `false`.
  - `meeting_links` (array of object, required): Scheduling pages the agent can book on during a call — typically one per sales rep plus a round-robin team page marked as the fallback. Default: `[]`.
    - `slug` (string, required): HubSpot scheduling page slug, as returned by the meeting-links API (e.g. 'julien-marchand'). Constraints: min length 1.
    - `label` (string, required): Name the agent recognises for this calendar (e.g. 'Julien Marchand'). Listed in the prompt and matched against what the caller asks for. Constraints: min length 1.
    - `duration_ms` (integer, required): Meeting duration in milliseconds, chosen among the durations the scheduling page offers (e.g. 1800000 for 30 minutes). Constraints: max 9007199254740991, > 0.
    - `is_fallback` (boolean, required): Marks the round-robin calendar the agent falls back to when the requested rep has no slot. At most one meeting link may set this.
    - `booking_url` (string, required, nullable): Public URL of the scheduling page (e.g. https://meetings-eu1.hubspot.com/julien). The agent books through the API and only texts this link to the caller when the booking fails and the call can receive an SMS. Null on calendars saved before this field existed. Default: `null`.
  - `post_call_sync` (object, optional): Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.
    - `enabled` (boolean, required): Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says. Default: `false`.
    - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties. Default: `[]`.
      - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
      - `hubspot_property` (string, required): Destination HubSpot contact property, by internal name (e.g. 'email', 'company', or a custom 'budget'). Constraints: min length 1.
- `slack` (object, optional, nullable): Slack notification config. When set, posts a message to the chosen channel after a call ends with one of the configured outcomes.
  - `connection_id` (string, required): The Nango connection ID linking the org's Slack workspace to Revox.
  - `channels` (array of object, required): The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
    - `id` (string, required): The Slack channel ID (e.g. 'C01234567').
    - `name` (string, optional, nullable): Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
- `teams` (object, optional, nullable): Microsoft Teams config. When set with at least one channel, the post-call agent can post to those channels when the post-call instructions ask for it.
  - `connection_id` (string, required): The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.
  - `channels` (array of object, required): The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
    - `id` (string, required): The Microsoft Teams channel ID (e.g. '19:561fbdbb...@thread.tacv2').
    - `name` (string, optional, nullable): Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
    - `team_id` (string, required): The ID of the team the channel belongs to. Needed to post.
    - `team_name` (string, optional, nullable): Human-readable team name. Channel names repeat across teams (every team has a 'General'), so the team name is what tells two of them apart.
- `zoho` (object, optional, nullable): Zoho CRM integration config. When set, upserts the prospect (keyed on phone) into the chosen module and attaches a Note with the call summary after a call ends with one of the configured outcomes.
  - `connection_id` (string, required): The Nango connection ID linking the org's Zoho CRM account to Revox.
  - `module` (string, required): Zoho module the prospect record is upserted into (e.g. 'Leads' or 'Contacts'). Constraints: min length 1.
  - `log_call_activity` (boolean, required): When true, also log the call as a record in Zoho's Calls module (related to the upserted prospect via Who_Id).
  - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.
    - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
    - `zoho_field` (string, required): Destination Zoho field API name on the upserted record (e.g. 'Email', 'Company', or a custom 'Budget__c'). Constraints: min length 1.
  - `template` (string, optional, nullable): Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.
- `custom_tools` (array of object, optional, nullable): Custom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution.
  - `name` (string, required): Unique tool name in lowercase_snake_case (e.g. check_inventory) Constraints: min length 1, pattern ^[a-z][a-z0-9_]*$.
  - `description` (string, required): Human-readable description of what the tool does, used by the LLM to decide when to call it Constraints: min length 1.
  - `method` (enum (string), required): HTTP method to use when calling the API endpoint One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
  - `url` (string, required): Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values Constraints: min length 1.
  - `headers` (array of object, required): HTTP headers to include in the request. Values support {{variable}} placeholders Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required)
  - `query_params` (array of object, required): Query string parameters appended to the URL. Values support {{variable}} placeholders Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required)
  - `body_template` (string, required, nullable): JSON body template for the request. Use quoted {{variable}} placeholders (e.g. "{{name}}") for dynamic values Default: `null`.
  - `input_schema` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required): Schema defining the parameters the LLM should extract from the conversation to pass to this tool
- `from_phone_number` (string, optional, nullable): Override the default outbound phone number for calls placed with this assistant. Must be a phone number owned by the organization in E.164 format (e.g. +1234567890). When null, the organization's default phone number is used.
- `logo_url` (string (uri), optional, nullable): Public URL of the brand logo shown on the assistant's demo page. Upload a new logo via POST /assistants/:id/logo. Set explicitly to null to clear it.
- `precall_lookup_url` (string, optional, nullable): Inbound calls only. URL fetched over HTTP GET right before the call is answered, with `{{phone}}` replaced by the caller's number in E.164 format (URL-encoded), to fill the `{{variable}}` placeholders the assistant declares. It answers either `{"prompt_variables": {...}}` or a flat JSON object whose top-level fields are the variables. The call is always answered: if the endpoint fails, takes more than 3 seconds, answers 404 or leaves a variable out, the missing variables are marked as not provided. Must be an http(s) URL containing `{{phone}}`. When null, no lookup is performed. Constraints: max length 2000.
- `precall_lookup_headers` (array of object, optional, nullable): HTTP headers sent with the pre-call lookup request, e.g. an API key. Null or empty when the endpoint needs none.
  - `key` (string, required): Constraints: max length 200, pattern ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$.
  - `value` (string, required): Constraints: min length 1, max length 4000.
- `name` (string, optional)

### Example request

```bash
curl -X PATCH https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminder"
  }'
```

### Responses

#### 200: Success

- `assistant` ([Assistant](https://www.getrevox.com/docs/api/objects/assistant.md), required)
- `unpatchedCallsNotice` (object, optional)
  - `count` (number, required)
  - `variables` (array of string, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `error` (string, required)

---

## Delete an assistant

`DELETE https://www.getrevox.com/api/assistants/{id}`

Permanently delete an assistant by its ID. Any future calls referencing this assistant ID will fail. Existing call records that used this assistant are not affected.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X DELETE https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

---

## Get assistant statistics

`GET https://www.getrevox.com/api/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. The perimeter is invariant and matches the call-history page filtered on this agent and the inbound direction: calls with your organization id, this assistant id, direction 'inbound' and not soft-deleted — no status or date filter. All weekday/hour/week bucketing happens server-side in the assistant's reporting timezone (currently fixed to Europe/Paris). 'has_activity' is false when no inbound call exists yet (the UI then shows the empty state, never a zero-count test), and 'weekly_average' is null in that case. Durations cover answered calls only (last attempt with both answered_at and ended_at); the rest are counted as unanswered.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X GET https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/statistics \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `statistics` (object, required)
  - `assistant` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `timezone` (string, required)
    - `has_activity` (boolean, required)
  - `activity` (object, required)
    - `calls_total` (number, required)
    - `weekly_average` (number, required, nullable)
    - `weeks` (array of object, required)
      - `week_start` (string, required)
      - `count` (number, required)
  - `weekdays` (object, required)
    - `days` (array of number, required)
    - `busiest_day` (object, required, nullable)
      - `index` (number, required)
      - `count` (number, required)
    - `busiest_hour` (object, required, nullable)
      - `start` (number, required)
      - `count` (number, required)
  - `durations` (object, required)
    - `average_seconds` (number, required, nullable)
    - `buckets` (object, required)
      - `under_1` (number, required)
      - `from_1_to_2` (number, required)
      - `from_2_to_3` (number, required)
      - `over_3` (number, required)
    - `unanswered` (number, required)

#### 404: Not found in your organization

- `error` (string, required)

---

## Clone an assistant

`POST https://www.getrevox.com/api/assistants/{id}/clone`

Create a full copy of an existing assistant, including every configuration field. The new assistant has the same configuration as the source, with the name suffixed by "(Copy)" and a freshly generated API key. Pass `type: "sub-assistant"` to import a standalone assistant into a multi-step flow: the copy keeps the source name, is hidden from the assistants list, and is ready to be wired into a flow via the /assistants/:id/edges endpoints.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/clone \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `assistant` ([Assistant](https://www.getrevox.com/docs/api/objects/assistant.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `error` (string, required)

#### 500: Server error

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Check an assistant's setup

`POST https://www.getrevox.com/api/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. Call it after your last change to the assistant. Returns at most one issue per kind, each with the fix to apply when one exists; an empty list means nothing major was found. The result is stored: while the setup is unchanged it comes back instantly, a fresh check takes a few seconds. Multi-step assistants are not checked.

### Path parameters

- `id` (string, required)

### Request body (JSON)

- `locale` (enum (string), required): Language of the issue messages. One of: `fr`, `en`.
- `dismiss` (integer, optional): Index of an issue to ignore: it is no longer returned until the setup changes. Constraints: min -9007199254740991, max 9007199254740991.

### Example request

```bash
curl -X POST https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/setup-check \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "fr"
  }'
```

### Responses

#### 200: Success

- `issues` (array of [AssistantSetupIssue](https://www.getrevox.com/docs/api/objects/assistant-setup-issue.md), required)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## List an assistant's calendars

`GET https://www.getrevox.com/api/assistants/{id}/calendars`

The calendars the assistant books meetings on during a call, in the order they were added. Each has a handle the prompt mentions, a status, and the account it is connected to.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X GET https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/calendars \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `calendars` (array of [AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Add a calendar to an assistant

`POST https://www.getrevox.com/api/assistants/{id}/calendars`

Add a calendar on a provider, before any account is connected to it. Connect it next, or create an invite link for a colleague to connect their own: connecting gives it the handle the prompt mentions, named after the account (`google_calendar_aric_at_getrevox.com`).

### Path parameters

- `id` (string, required)

### Request body (JSON)

- `provider` (enum (string), required): One of: `google-calendar`, `calendly`, `cal-com-oauth`.

### Example request

```bash
curl -X POST https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/calendars \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "cartesia"
  }'
```

### Responses

#### 200: Success

- `calendar` ([AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Change a calendar's settings

`PATCH https://www.getrevox.com/api/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.

### Path parameters

- `id` (string, required)
- `calendarId` (string, required)

### Request body (JSON)

- `settings` (one of, required): Must match the calendar's provider.
  - One of, **Option 1** (object)
    - `calendar_id` (string, required): The Google calendar to book on. (eg: primary)
    - `time_zone` (string, required): The timezone of the opening hours. (eg: Europe/Paris)
    - `duration_minutes` (integer, required): Constraints: min 5, max 480. Default: `30`.
    - `days` (array of integer, required): The open days, 0 is Sunday. Default: `[1,2,3,4,5]`.
    - `start_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"09:00"`.
    - `end_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"18:00"`.
    - `google_meet` (boolean, required): Adds a Google Meet link to the meeting. Default: `true`.
  - One of, **Option 2** (object)
    - `event_type_id` (string, required): The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5) Constraints: min length 1.
  - One of, **Option 3** (object)
    - `event_type_id` (string, required): The Cal.com event type to schedule. (eg: 7081322) Constraints: min length 1.

### Example request

```bash
curl -X PATCH https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/calendars/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "calendar_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "time_zone": "string",
      "duration_minutes": 30,
      "days": [
        1,
        2,
        3,
        4,
        5
      ],
      "start_time": "09:00",
      "end_time": "18:00",
      "google_meet": true
    }
  }'
```

### Responses

#### 200: Success

- `calendar` ([AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Remove a calendar from an assistant

`DELETE https://www.getrevox.com/api/assistants/{id}/calendars/{calendarId}`

The agent stops booking on it. The account connection is deleted too, unless another calendar still uses it.

### Path parameters

- `id` (string, required)
- `calendarId` (string, required)

### Example request

```bash
curl -X DELETE https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/calendars/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Connect an account to a calendar

`PUT https://www.getrevox.com/api/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). Reconnecting the same account keeps the handle. Google's primary calendar, or the account's only event type, is picked right away; otherwise pick one with the selection endpoint.

### Path parameters

- `id` (string, required)
- `calendarId` (string, required)

### Request body (JSON)

- `connection_id` (string, required): The Nango connection ID linking an account of the calendar's provider to Revox.

### Example request

```bash
curl -X PUT https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/calendars/3c90c3cc-0d44-4b50-8888-8dd25736052a/connection \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }'
```

### Responses

#### 200: Success

- `calendar` ([AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Disconnect a calendar's account

`DELETE https://www.getrevox.com/api/assistants/{id}/calendars/{calendarId}/connection`

The calendar keeps its handle, which the agent then treats as not available, and waits for an account. Its invite link is revoked.

### Path parameters

- `id` (string, required)
- `calendarId` (string, required)

### Example request

```bash
curl -X DELETE https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/calendars/3c90c3cc-0d44-4b50-8888-8dd25736052a/connection \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `calendar` ([AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Create an invite link for a calendar

`POST https://www.getrevox.com/api/assistants/{id}/calendars/{calendarId}/invite`

A link for a colleague without a Revox account to connect their own account on the calendar's provider. A new link replaces the previous one, which stops working.

### Path parameters

- `id` (string, required)
- `calendarId` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/calendars/3c90c3cc-0d44-4b50-8888-8dd25736052a/invite \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `calendar` ([AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Revoke a calendar's invite link

`DELETE https://www.getrevox.com/api/assistants/{id}/calendars/{calendarId}/invite`

### Path parameters

- `id` (string, required)
- `calendarId` (string, required)

### Example request

```bash
curl -X DELETE https://www.getrevox.com/api/assistants/3c90c3cc-0d44-4b50-8888-8dd25736052a/calendars/3c90c3cc-0d44-4b50-8888-8dd25736052a/invite \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `calendar` ([AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Get phone number history across the organization

`GET https://www.getrevox.com/api/calls/phone-history`

Returns a map of phone numbers to the number of calls and associated campaigns across the entire organization. Useful for detecting contacts that have already been reached.

### Example request

```bash
curl -X GET https://www.getrevox.com/api/calls/phone-history \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `phone_history` (map of object, required)
  - `count` (number, required)
  - `campaigns` (array of object, required)
    - `id` (string, required)
    - `name` (string, required)
  - `last_called_at` (string, required, nullable)
  - `last_outcome` (enum (string), required, nullable): One of: `not_interested`, `interested`, `completed`, `requested_callback_later`. Default: `null`.
  - `reached_human` (boolean, required)
  - `do_not_contact` (boolean, required)
  - `hot` (boolean, required)

---

## Find which phone numbers are on the do-not-call list

`POST https://www.getrevox.com/api/calls/screen-do-not-call`

Returns the subset of the submitted numbers that must not be called. Unlike /calls/phone-history — which only knows numbers the organization has already called — this screens arbitrary numbers, so a contact being imported for the first time can be caught before the campaign is created.

### Request body (JSON)

- `phone_numbers` (array of string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/calls/screen-do-not-call \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": [
      "+33612345678"
    ]
  }'
```

### Responses

#### 200: Success

- `blocked` (array of string, required)

---

## Get call by ID

`GET https://www.getrevox.com/api/call/{id}`

Retrieve the full details of a call order by its unique ID. The response includes the call status, call attempts, transcript, recording URL, timestamps, and metadata. Use this endpoint to poll for call completion or inspect results after a call has finished.

### Path parameters

- `id` (string, required): The ID of the call to get.

### Example request

```bash
curl -X GET https://www.getrevox.com/api/call/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `call` ([Call](https://www.getrevox.com/docs/api/objects/call.md), required)

#### 403: The API key's organization cannot access this resource

- `error` (string, required)

#### 404: Not found in your organization

- `error` (string, required)

---

## Place a call

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

Place a new outbound call order. Provide either an existing assistant ID or a custom assistant configuration. The call can be scheduled for a specific time or started immediately. A single call order may be resolved over multiple call attempts spanning up to a few days, with automatic retries when voicemail is detected. You can also set concurrency limits and pass prompt variables for dynamic personalization.

### Request body (JSON)

- `phone_number` (string, required): The phone number to call in the E.164 format. Example: +1234567890
- `skip_calling_window` (boolean, optional): Bypass the calling-window check for this call so it dials even outside the assistant's configured window. Use for immediate 'call now' dials.
- `timezone` (string, optional, nullable): IANA timezone in which this call's calling windows and allowed days are evaluated, in place of the assistant's call_retry_config.timezone, for this call only. Examples: 'America/Los_Angeles', 'Europe/Paris'. Null: the callee's own timezone, derived from the country of phone_number. Omitted: the assistant's setting. Use it when you know where the callee is better than their country code does, e.g. a US number on Pacific time.
- `from_phone_number` (string, optional): The phone number to use for making the call (e.g., +1234567890). If not provided, uses the default trunk.
- `call_twice_in_a_row` (boolean, optional): Double call for this call only, in place of the assistant's call_retry_config.call_twice_in_a_row. True: if the first attempt reaches nobody (no answer, declined, voicemail, call screening nobody took), the second attempt is dialed within seconds, from the same caller number. Each call is an attempt: the double call counts as 2 when both calls happen, so true raises a max_retry_attempts of 1 to 2. Omitted: the assistant's setting.
- `prompt_variables` (map of string, optional): Variables to interpolate into the prompt. Wether you use an assistant_id or an assistant object, this will be used to interpolate the variables into the prompt.
- `metadata` (map of string, optional): Metadata to store with the call.
- `assistant_id` (string (uuid), optional): The ID of the assistant to use for this call.
- `assistant` (object, optional): You can provide a custom assistant configuration here. If you don't provide an assistant_id, this assistant object will be used for this call.
  - `type` (enum (string), optional): Assistant kind. 'standalone' (default) is a normal assistant, 'multi-step' orchestrates a flow of sub-assistants, 'sub-assistant' is a step inside a multi-step flow (hidden from the assistants list). Flow transitions are managed via the /assistants/:id/edges endpoints, not on the assistant itself. One of: `standalone`, `multi-step`, `sub-assistant`.
  - `position` (object, optional, nullable): Canvas position of this assistant's node in its multi-step flow editor.
    - `x` (number, required)
    - `y` (number, required)
  - `start_step_name` (string, optional, nullable): Name of a multi-step flow's start step. Defaults to the assistant's name. Constraints: max length 255.
  - `prompt` (string, required): The prompt to use for the call. This will be given to the LLM (gpt-4.1)
  - `post_call_prompt` (string, optional, nullable): Instructions the agent follows once the call has ended: who to email, when to text, what to post on Slack or Teams. Plain language, no template syntax. Empty or null means no post-call agent runs.
  - `first_sentence` (string, optional): The first sentence to use for the call. This will be given to the LLM
  - `first_sentence_mode` (enum (string), optional): How the first sentence should be handled. "generated" means the LLM will generate a response based on the first_sentence instruction. "static" means the first_sentence will be spoken exactly as provided. "none" means the agent will not speak first and will wait for the user. One of: `generated`, `static`, `none`.
  - `end_of_call_sentence` (string, optional): Optional message to say when the agent decides to end the call.
  - `voice` (object, optional): The voice to use for the call. You can get the list of voices using the /voices endpoint
    - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
    - `id` (string, required): The ID of the voice. Constraints: min length 1.
    - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
    - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
    - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
  - `voice_languages` (array of object, optional, nullable): Extra languages for a multilingual assistant, each with its own voice (any provider). A call picks one with a `language` entry in its prompt_variables (a language code such as "es", or a name such as "Spanish"); otherwise the phone number's country picks one, and failing that the call runs in the language of `voice`, which cannot be listed here. A changed voice is applied to the calls in that language that have not completed yet; a language still used by such a call cannot be removed.
    - `language` (enum (string), required): The language contacts are called in with this voice. One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.
    - `voice` (object, required): The voice used for contacts whose language is this language.
      - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
      - `id` (string, required): The ID of the voice. Constraints: min length 1.
      - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
      - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
      - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
  - `cartesia_dictionary_pronunciation_id` (string, optional, nullable): Optional Cartesia pronunciation dictionary ID to use for this assistant's calls. Set null to unlink it. Constraints: min length 1.
  - `llm_model` (one of, optional)
    - One of, **Recommended** (object)
      - `type` (string (constant), required): The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.
    - One of, **Gpt41Priority** (object)
      - `type` (string (constant), required): OpenAI gpt-4.1 on the priority tier, with gpt-4.1-mini answering a turn when gpt-4.1 is slow to respond. No per-assistant configuration.
    - One of, **Realtime** (object)
      - `type` (string (constant), required): Use a model from Realtime.
      - `provider` (enum (string), required): The provider to use from Realtime. eg: openai, google. One of: `openai`, `google`.
      - `realtime_model_id` (string, required): The model ID to use from Realtime. eg: gpt-4.1
      - `realtime_voice_id` (string, optional): Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck). Constraints: min length 1.
  - `webhook_url` (string, optional): The webhook URL to call when the call is completed.
  - `max_call_duration_secs` (number, optional): The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.
  - `max_duration_end_message` (string, optional, nullable): Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If not set, the call ends silently. Constraints: max length 150.
  - `structured_output_config` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), optional): The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).
  - `structured_output_prompt` (string, optional, nullable): Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
  - `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), optional)
  - `background_sound` (enum (string), optional, nullable): Ambient background sound to play during the call. null/omitted disables it. One of: `audio/office.ogg`, `audio/waves.m4a`.
  - `background_sound_volume` (number, optional): Volume of the ambient background sound (0 = silent, 1 = max). Constraints: min 0, max 1.
  - `thinking_sound` (enum (string), optional, nullable): Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null/omitted disables it. One of: `city-ambience.ogg`, `forest-ambience.ogg`, `office-ambience.ogg`, `crowded-room.ogg`, `keyboard-typing.ogg`, `keyboard-typing2.ogg`, `hold_music.ogg`.
  - `thinking_sound_volume` (number, optional): Volume of the thinking sound (0 = silent, 1 = max). Constraints: min 0, max 1.
  - `thinking_sound_probability` (number, optional): Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking. Constraints: min 0, max 1.
  - `transfer_destinations` (array of object, optional, nullable): Where calls can be transferred to when users ask to speak to a human. With a single entry the assistant always transfers there; with several, it picks one at transfer time by applying the routing rules written in the assistant's own prompt (which refer to the destination labels). Empty or null disables transfer.
    - `label` (string, required): Human-meaningful name for this destination (e.g. "Sales"). The assistant's prompt refers to these labels when describing who to transfer to. Constraints: min length 1, max length 60.
    - `phone_number` (string, required): Destination phone number in E.164 format (e.g. +1234567890).
  - `human_transfer_mode` (enum (string), optional, nullable): When transfer_destinations is non-empty: "warm" (AI bridges) or "cold" (SIP REFER; trunk must allow REFER/PSTN). Omit or null when transfer is disabled. One of: `warm`, `cold`.
  - `warm_transfer_summary_instructions` (string, optional, nullable): When using warm transfer: extra instructions for the supervisor handoff summary. If null or empty, the API uses the product default briefing when the call is loaded for the agent.
  - `warm_transfer_voice_speed` (number, optional, nullable): When using warm transfer: voice speed used only while the AI briefs the human colleague. Same range as voice.speed. Omit or null to brief at the assistant's voice speed. Constraints: min 0.6, max 1.5.
  - `ivr_navigation_enabled` (boolean, optional): Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.
  - `voicemail_message` (string, optional, nullable): If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately. Left on the first attempt only (second dial of a double call). Takes the same {{variables}} as the prompt (e.g. "Hi {{first_name}}, this is Julie from Acme, please call us back.").
  - `stt_context` (object, optional, nullable): Assistant-level speech-to-text context: structured `general` key/value pairs plus a list of domain `terms`. Prompt-derived context is merged in without replacing existing entries.
    - `general` (array of object, required): Default: `[]`.
      - `key` (string, required): Constraints: min length 1.
      - `value` (string, required): Constraints: min length 1.
    - `terms` (array of string, required): Default: `[]`.
  - `stt_model` (enum (string), optional): Transcriber (speech-to-text) model. Defaults to the newest Soniox realtime model when omitted. One of: `stt-rt-v4`, `stt-rt-v5`.
  - `stt_endpoint_sensitivity` (number, optional, nullable): Soniox endpoint sensitivity override (-1 to 1). Higher values finalize transcripts sooner. Null or omitted: the agent's default tuning. Constraints: min -1, max 1.
  - `stt_endpoint_latency_level` (integer, optional, nullable): Soniox endpoint latency adjustment level override (0 to 3). Higher values reduce endpoint latency at a slight accuracy cost. Null or omitted: the agent's default tuning. Constraints: min 0, max 3.
  - `stt_bvc_filter_enabled` (boolean, optional): When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output. Default true.
  - `krisp_viva_filter_enabled` (boolean, optional): When true, the agent's noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony. Default false.
  - `first_sentence_delay_ms` (integer, optional): Delay in milliseconds before speaking the first sentence. Default: 400. Constraints: min 0, max 9007199254740991.
  - `calendly` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
    - `connection_id` (string, required): The connection ID representing the link between your Calendly account and Revox.
    - `event_type_id` (string, required): The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5) Constraints: min length 1.
  - `cal` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
    - `connection_id` (string, required): The connection ID representing the link between your Cal.com account and Revox.
    - `event_type_id` (string, required): The Cal.com event type to schedule. (eg: 7081322) Constraints: min length 1.
  - `google_calendar` (object, optional, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
    - `calendar_id` (string, required): The Google calendar to book on. (eg: primary)
    - `time_zone` (string, required): The timezone of the opening hours. (eg: Europe/Paris)
    - `duration_minutes` (integer, required): Constraints: min 5, max 480. Default: `30`.
    - `days` (array of integer, required): The open days, 0 is Sunday. Default: `[1,2,3,4,5]`.
    - `start_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"09:00"`.
    - `end_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"18:00"`.
    - `google_meet` (boolean, required): Adds a Google Meet link to the meeting. Default: `true`.
    - `connection_id` (string, required): The connection ID representing the link between your Google account and Revox.
  - `hubspot` (object, optional, nullable): HubSpot Meetings config. When set with at least one meeting link, the agent can read a rep's real availability and book the meeting natively in HubSpot during the call.
    - `connection_id` (string, required): The Nango connection ID linking the org's HubSpot account to Revox.
    - `precall_lookup_enabled` (boolean, required): Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up. Default: `false`.
    - `meeting_links` (array of object, required): Scheduling pages the agent can book on during a call — typically one per sales rep plus a round-robin team page marked as the fallback. Default: `[]`.
      - `slug` (string, required): HubSpot scheduling page slug, as returned by the meeting-links API (e.g. 'julien-marchand'). Constraints: min length 1.
      - `label` (string, required): Name the agent recognises for this calendar (e.g. 'Julien Marchand'). Listed in the prompt and matched against what the caller asks for. Constraints: min length 1.
      - `duration_ms` (integer, required): Meeting duration in milliseconds, chosen among the durations the scheduling page offers (e.g. 1800000 for 30 minutes). Constraints: max 9007199254740991, > 0.
      - `is_fallback` (boolean, required): Marks the round-robin calendar the agent falls back to when the requested rep has no slot. At most one meeting link may set this.
      - `booking_url` (string, required, nullable): Public URL of the scheduling page (e.g. https://meetings-eu1.hubspot.com/julien). The agent books through the API and only texts this link to the caller when the booking fails and the call can receive an SMS. Null on calendars saved before this field existed. Default: `null`.
    - `post_call_sync` (object, optional): Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.
      - `enabled` (boolean, required): Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says. Default: `false`.
      - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties. Default: `[]`.
        - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
        - `hubspot_property` (string, required): Destination HubSpot contact property, by internal name (e.g. 'email', 'company', or a custom 'budget'). Constraints: min length 1.
  - `slack` (object, optional, nullable): Slack notification config. When set, posts a message to the chosen channel after a call ends with one of the configured outcomes.
    - `connection_id` (string, required): The Nango connection ID linking the org's Slack workspace to Revox.
    - `channels` (array of object, required): The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
      - `id` (string, required): The Slack channel ID (e.g. 'C01234567').
      - `name` (string, optional, nullable): Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
  - `teams` (object, optional, nullable): Microsoft Teams config. When set with at least one channel, the post-call agent can post to those channels when the post-call instructions ask for it.
    - `connection_id` (string, required): The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.
    - `channels` (array of object, required): The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
      - `id` (string, required): The Microsoft Teams channel ID (e.g. '19:561fbdbb...@thread.tacv2').
      - `name` (string, optional, nullable): Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
      - `team_id` (string, required): The ID of the team the channel belongs to. Needed to post.
      - `team_name` (string, optional, nullable): Human-readable team name. Channel names repeat across teams (every team has a 'General'), so the team name is what tells two of them apart.
  - `zoho` (object, optional, nullable): Zoho CRM integration config. When set, upserts the prospect (keyed on phone) into the chosen module and attaches a Note with the call summary after a call ends with one of the configured outcomes.
    - `connection_id` (string, required): The Nango connection ID linking the org's Zoho CRM account to Revox.
    - `module` (string, required): Zoho module the prospect record is upserted into (e.g. 'Leads' or 'Contacts'). Constraints: min length 1.
    - `log_call_activity` (boolean, required): When true, also log the call as a record in Zoho's Calls module (related to the upserted prospect via Who_Id).
    - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.
      - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
      - `zoho_field` (string, required): Destination Zoho field API name on the upserted record (e.g. 'Email', 'Company', or a custom 'Budget__c'). Constraints: min length 1.
    - `template` (string, optional, nullable): Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.
  - `custom_tools` (array of object, optional, nullable): Custom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution.
    - `name` (string, required): Unique tool name in lowercase_snake_case (e.g. check_inventory) Constraints: min length 1, pattern ^[a-z][a-z0-9_]*$.
    - `description` (string, required): Human-readable description of what the tool does, used by the LLM to decide when to call it Constraints: min length 1.
    - `method` (enum (string), required): HTTP method to use when calling the API endpoint One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
    - `url` (string, required): Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values Constraints: min length 1.
    - `headers` (array of object, required): HTTP headers to include in the request. Values support {{variable}} placeholders Default: `[]`.
      - `key` (string, required): Constraints: min length 1.
      - `value` (string, required)
    - `query_params` (array of object, required): Query string parameters appended to the URL. Values support {{variable}} placeholders Default: `[]`.
      - `key` (string, required): Constraints: min length 1.
      - `value` (string, required)
    - `body_template` (string, required, nullable): JSON body template for the request. Use quoted {{variable}} placeholders (e.g. "{{name}}") for dynamic values Default: `null`.
    - `input_schema` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required): Schema defining the parameters the LLM should extract from the conversation to pass to this tool
  - `from_phone_number` (string, optional, nullable): Override the default outbound phone number for calls placed with this assistant. Must be a phone number owned by the organization in E.164 format (e.g. +1234567890). When null, the organization's default phone number is used.
  - `logo_url` (string (uri), optional, nullable): Public URL of the brand logo shown on the assistant's demo page. Upload a new logo via POST /assistants/:id/logo. Set explicitly to null to clear it.
  - `precall_lookup_url` (string, optional, nullable): Inbound calls only. URL fetched over HTTP GET right before the call is answered, with `{{phone}}` replaced by the caller's number in E.164 format (URL-encoded), to fill the `{{variable}}` placeholders the assistant declares. It answers either `{"prompt_variables": {...}}` or a flat JSON object whose top-level fields are the variables. The call is always answered: if the endpoint fails, takes more than 3 seconds, answers 404 or leaves a variable out, the missing variables are marked as not provided. Must be an http(s) URL containing `{{phone}}`. When null, no lookup is performed. Constraints: max length 2000.
  - `precall_lookup_headers` (array of object, optional, nullable): HTTP headers sent with the pre-call lookup request, e.g. an API key. Null or empty when the endpoint needs none.
    - `key` (string, required): Constraints: max length 200, pattern ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$.
    - `value` (string, required): Constraints: min length 1, max length 4000.
- `concurrency` (object, optional): Limit the number of concurrent calls for a given concurrency key. The limit itself is set server-side; omit this to leave the call ungrouped (bounded only by your organization's limit).
  - `key` (string, required): Groups this call with every other call sharing the same key, for concurrency purposes.
- `campaign` (object, optional): Group this call under a campaign, to follow its statistics in the dashboard. Nothing to create beforehand: the campaign exists as soon as a call names it, and it uses the assistant of that first call. Requires assistant_id, and cannot be combined with concurrency: the call follows the campaign's own concurrency limit, retry settings and pause. Returns 409 when the campaign was cancelled or uses another assistant. Calling the same number twice in a campaign counts as one contact.
  - `name` (string, required): The campaign's name, case-insensitive. Created on first use, reused by every later call that sends it. Constraints: min length 1, max length 255.
- `scheduled_at` (one of, optional): Schedule the call to start at a specific date and time (ISO 8601 format). If not provided, the call will start immediately.
  - One of, **string** (string (date-time))
  - One of, **Option 2** (any)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/call \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+33612345678"
  }'
```

### Responses

#### 200: Success

- `call` ([Call](https://www.getrevox.com/docs/api/objects/call.md), required)

#### 402: Not enough credits on the organization

- `error` (string, required)
- `code` (string (constant), required)

#### 409: Conflict with the resource's current state

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Get calls

`POST https://www.getrevox.com/api/call/search`

Retrieve a paginated list of call attempts. Each entry includes the call status, phone number, assistant used, transcript, and timestamps. Use the page and page_size query parameters to navigate through results.

### Request body (JSON)

- `query` (string, optional)
- `statuses` (array of enum (string), required): Default: `[]`.
- `directions` (array of enum (string), required): Default: `[]`.
- `results` (array of enum (string), required): Default: `[]`.
- `outcomes` (array of enum (string), required): Default: `[]`.
- `assistant_ids` (array of string, required): Default: `[]`.
- `campaign_ids` (array of string, required): Default: `[]`.
- `from_phone_numbers` (array of string, required): Default: `[]`.
- `assignee_ids` (array of one of, required): Default: `[]`.
  - One of, **string** (string)
  - One of, **string** (string (constant))
- `variables` (array of object, optional)
  - `key` (string, required)
  - `value` (string, required)
- `to_phone_number` (string, optional)
- `call_ids` (array of string, optional)
- `page` (integer, required): Constraints: min 1, max 9007199254740991. Default: `1`.
- `page_size` (integer, required): Constraints: min 1, max 100. Default: `50`.
- `sort_by` (string, optional)
- `sort_direction` (enum (string), optional): One of: `asc`, `desc`.

### Example request

```bash
curl -X POST https://www.getrevox.com/api/call/search \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "statuses": [],
    "directions": [],
    "results": [],
    "outcomes": [],
    "assistant_ids": [],
    "campaign_ids": [],
    "from_phone_numbers": [],
    "assignee_ids": [],
    "page": 1,
    "page_size": 50
  }'
```

### Responses

#### 200: Success

- `calls` (array of [Call](https://www.getrevox.com/docs/api/objects/call.md), required)
- `total_count` (number, required)

---

## Export calls history

`POST https://www.getrevox.com/api/call/export`

Export a list of call attempts as a CSV file. Large exports are split into several files of at most 4MB each: when the response carries a non-null next_offset, call the endpoint again with that value as offset to get the next file.

### Request body (JSON)

- `filters` (object, required)
  - `query` (string, optional)
  - `statuses` (array of enum (string), required): Default: `[]`.
  - `directions` (array of enum (string), required): Default: `[]`.
  - `results` (array of enum (string), required): Default: `[]`.
  - `outcomes` (array of enum (string), required): Default: `[]`.
  - `assistant_ids` (array of string, required): Default: `[]`.
  - `campaign_ids` (array of string, required): Default: `[]`.
  - `from_phone_numbers` (array of string, required): Default: `[]`.
  - `assignee_ids` (array of one of, required): Default: `[]`.
    - One of, **string** (string)
    - One of, **string** (string (constant))
  - `variables` (array of object, optional)
    - `key` (string, required)
    - `value` (string, required)
  - `to_phone_number` (string, optional)
  - `call_ids` (array of string, optional)
  - `page` (integer, required): Constraints: min 1, max 9007199254740991. Default: `1`.
  - `page_size` (integer, required): Constraints: min 1, max 50000. Default: `50000`.
  - `sort_by` (string, optional)
  - `sort_direction` (enum (string), optional): One of: `asc`, `desc`.
- `offset` (integer, required): Number of already-exported rows to skip, within the filters' page/page_size window. Pass the next_offset value from the previous response to fetch the next file of a split export. Constraints: min 0, max 9007199254740991. Default: `0`.
- `include_structured_output_fields` (boolean, optional): Whether to include the structured output fields in the CSV file. These are generated by our AI agent during call analysis phase.
- `include_metadata` (boolean, optional): Whether to include the metadata in the CSV file. These are the fields you (optionally) attached when placing the call.

### Example request

```bash
curl -X POST https://www.getrevox.com/api/call/export \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "statuses": [],
      "directions": [],
      "results": [],
      "outcomes": [],
      "assistant_ids": [],
      "campaign_ids": [],
      "from_phone_numbers": [],
      "assignee_ids": [],
      "page": 1,
      "page_size": 50000
    },
    "offset": 0
  }'
```

### Responses

#### 200: Success

- `csv` (string, required)
- `filename` (string, required)
- `next_offset` (integer, required, nullable): Non-null when the export was split because this file reached the 4MB cap: pass it as offset in a follow-up call to get the next file. Null when this file completes the export. Constraints: min -9007199254740991, max 9007199254740991.

---

## Pause a call

`POST https://www.getrevox.com/api/call/{id}/pause`

Pause a call's retry loop. The current in-progress attempt (if any) will finish, but no new attempts will be started until the call is resumed.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/call/3c90c3cc-0d44-4b50-8888-8dd25736052a/pause \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Resume a paused call

`POST https://www.getrevox.com/api/call/{id}/resume`

Resume a previously paused call. The retry loop will continue from where it left off.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/call/3c90c3cc-0d44-4b50-8888-8dd25736052a/resume \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Cancel a call

`POST https://www.getrevox.com/api/call/{id}/cancel`

Stop a call's future attempts. A call that has not started dialing yet is cancelled right away. A call whose attempt is already in progress is not hung up: that attempt finishes, and no retry or callback is scheduled after it. Returns 409 when the call is already in a terminal status.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/call/3c90c3cc-0d44-4b50-8888-8dd25736052a/cancel \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 409: Conflict with the resource's current state

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## List campaigns

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

Retrieve all campaigns for your organization, including both active and completed ones.

### Example request

```bash
curl -X GET https://www.getrevox.com/api/campaigns \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `campaigns` (array of [Campaign](https://www.getrevox.com/docs/api/objects/campaign.md), required)

---

## Create a campaign

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

Create a new outbound calling campaign. Every contact is materialized as a call in the `not_launched` status — nothing is dialed. Use POST /campaigns/:id/launch-calls to send them.

### Request body (JSON)

- `name` (string, required): The name of the campaign Constraints: min length 1.
- `assistant_id` (string (uuid), required): The ID of the assistant to use
- `from_phone_number` (string, optional): The phone number to use for outbound calls (E.164 format, e.g., +1234567890)
- `max_concurrent_calls` (number, optional): Maximum number of concurrent calls allowed for this campaign Constraints: min 1.
- `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), optional): Retry configuration for calls in this campaign. If not provided, uses the default retry config.
- `contacts` (array of object, required): The list of contacts to call
  - `to_phone_number` (string, required)
  - `prompt_variables` (any, required): Default: `{}`.

### Example request

```bash
curl -X POST https://www.getrevox.com/api/campaigns \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminder",
    "assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "contacts": [
      {
        "to_phone_number": "+33612345678",
        "prompt_variables": {}
      }
    ]
  }'
```

### Responses

#### 200: Success

- `campaign` ([Campaign](https://www.getrevox.com/docs/api/objects/campaign.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 402: Not enough credits on the organization

- `error` (string, required)
- `code` (string (constant), required)

---

## Get campaign by ID

`GET https://www.getrevox.com/api/campaigns/{id}`

Retrieve the full details of a single campaign by its unique ID. Can be used to poll for campaign completion.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X GET https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `campaign` ([Campaign](https://www.getrevox.com/docs/api/objects/campaign.md), required)

#### 404: Not found in your organization

- `error` (string, required)

---

## Update a campaign

`PATCH https://www.getrevox.com/api/campaigns/{id}`

Update a campaign's name, outbound number, retry configuration (calling hours, retry delay, max attempts) and concurrency cap. Changes are applied to the campaign's calls that have not completed yet. The assistant is fixed at creation; add contacts with POST /campaigns/:id/rows, and choose when calls go out with POST /campaigns/:id/launch-calls.

### Path parameters

- `id` (string, required)

### Request body (JSON)

- `name` (string, optional): Campaign display name Constraints: min length 1, max length 255.
- `from_phone_number` (string, optional, nullable): The phone number to use for outbound calls. Editable after launch; applied to the campaign's calls that have not completed yet.
- `max_concurrent_calls` (number, optional, nullable): Maximum concurrent calls. Editable after launch. Constraints: min 1.
- `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), optional, nullable): Override retry configuration (calling hours, retry delay, max attempts). Editable after launch; applied to the campaign's calls that have not completed yet, whose next attempt is re-scheduled under the new configuration. Its max_retry_attempts is only the default for max_attempts in POST /campaigns/:id/launch-calls.

### Example request

```bash
curl -X PATCH https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminder"
  }'
```

### Responses

#### 200: Success

- `campaign` ([Campaign](https://www.getrevox.com/docs/api/objects/campaign.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `error` (string, required)

---

## Delete a campaign

`DELETE https://www.getrevox.com/api/campaigns/{id}`

Permanently delete a campaign and all its associated rows. This action is irreversible. In-progress calls will not be affected, but no new calls will be placed.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X DELETE https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

---

## Get campaign rows

`GET https://www.getrevox.com/api/campaigns/{id}/rows`

Retrieve all contact rows for a campaign.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X GET https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a/rows \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `rows` (array of object, required)
  - `id` (string, required)
  - `row_index` (number, required)
  - `phone_number` (string, required)
  - `input_data` (map of string, required)
  - `call` ([Call](https://www.getrevox.com/docs/api/objects/call.md), optional)

#### 404: Not found in your organization

- `error` (string, required)

---

## Add contacts to a campaign

`POST https://www.getrevox.com/api/campaigns/{id}/rows`

Append contacts to an existing campaign. Each new contact is materialized as a call in the `not_launched` status — nothing is dialed until POST /campaigns/:id/launch-calls sends it. Contacts whose phone number is already in the campaign are skipped.

### Path parameters

- `id` (string, required)

### Request body (JSON)

- `contacts` (array of object, required)
  - `to_phone_number` (string, required)
  - `prompt_variables` (any, required): Default: `{}`.

### Example request

```bash
curl -X POST https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a/rows \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "to_phone_number": "+33612345678",
        "prompt_variables": {}
      }
    ]
  }'
```

### Responses

#### 200: Success

- `campaign` ([Campaign](https://www.getrevox.com/docs/api/objects/campaign.md), required)
- `added` (number, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `error` (string, required)

---

## Launch a campaign's calls

`POST https://www.getrevox.com/api/campaigns/{id}/launch-calls`

Send the campaign's calls matching a selection. In ai_first mode each call is handed to the admission scheduler at the requested time and follows the retry configuration from there. In speed_dial mode a live operator session dials them, and any call waiting on an AI retry is un-scheduled first so the same contact is never dialed twice. Calls the AI is already dialing are skipped; any other call, finished or cancelled included, is launched again.

### Path parameters

- `id` (string, required)

### Request body (JSON)

- `mode` (enum (string), required): One of: `ai_first`, `speed_dial`.
- `scheduled_at` (string (date-time), optional): When to place the calls (ISO 8601). Omit to launch now. ai_first only — a speed dial session cannot be scheduled.
- `max_attempts` (integer, optional): ai_first only. How many more attempts each launched call gets from now, replacing whatever it had left. Defaults to the campaign's max_retry_attempts. With the campaign's call_twice_in_a_row on, the double call counts as 2 of these attempts when both calls happen: with 1, there is no double call. Constraints: max 9007199254740991, > 0.
- `selection` (object, required)
  - `filters` (object, required)
    - `query` (string, optional)
    - `statuses` (array of enum (string), required): Default: `[]`.
    - `directions` (array of enum (string), required): Default: `[]`.
    - `results` (array of enum (string), required): Default: `[]`.
    - `outcomes` (array of enum (string), required): Default: `[]`.
    - `assignee_ids` (array of one of, required): Default: `[]`.
      - One of, **string** (string)
      - One of, **string** (string (constant))
    - `variables` (array of object, optional)
      - `key` (string, required)
      - `value` (string, required)
  - `rows` (object, required): Default: `{"mode":"all_except","call_ids":[]}`.
    - `mode` (enum (string), required): One of: `all_except`, `only`.
    - `call_ids` (array of string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a/launch-calls \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "ai_first",
    "selection": {
      "filters": {
        "statuses": [],
        "directions": [],
        "results": [],
        "outcomes": [],
        "assignee_ids": []
      },
      "rows": {
        "mode": "all_except",
        "call_ids": []
      }
    }
  }'
```

### Responses

#### 200: Success

- `launched` (number, required)
- `skipped` (object, required)
  - `active` (number, required)
  - `already_reached` (number, required)
  - `attempts_exhausted` (number, required)
  - `cancelled` (number, required)
- `session` (object, optional)
  - `id` (string (uuid), required)
  - `campaign_id` (string (uuid), required)
  - `status` (enum (string), required): One of: `dialing`, `connected`, `completed`, `stopped`, `errored`.
  - `outcome_filter` (array of enum (string), required)
  - `current_call_id` (string (uuid), required, nullable)
  - `total_targets` (number, required)
  - `dialed_count` (number, required)
  - `connected_count` (number, required)
  - `in_flight_calls` (array of [Call](https://www.getrevox.com/docs/api/objects/call.md), required)
  - `created_at` (one of, required)
    - One of, **string** (string (date-time))
    - One of, **Option 2** (any)
  - `ended_at` (one of, required, nullable)
    - One of, **string** (string (date-time))
    - One of, **Option 2** (any)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 402: Not enough credits on the organization

- `error` (string, required)
- `code` (string (constant), required)

#### 404: Not found in your organization

- `error` (string, required)

#### 409: Conflict with the resource's current state

- `error` (string, required)

---

## Get campaign statistics

`GET https://www.getrevox.com/api/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. All counts are over distinct E.164-normalized phone numbers, and the outcome-based categories derive exclusively from calls.outcome. Cascade percentages are null when their denominator is zero.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X GET https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a/statistics \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `statistics` (object, required)
  - `campaign` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `status` (enum (string), required): One of: `running`, `paused`, `completed`.
    - `is_cancelled` (boolean, required)
    - `first_activity_at` (any, required, nullable)
    - `last_activity_at` (any, required, nullable)
    - `agent_name` (string, required, nullable)
    - `max_attempts_per_contact` (number, required, nullable)
    - `timezone` (string, required)
    - `has_activity` (boolean, required)
  - `funnel` (object, required)
    - `called` (object, required)
      - `count` (number, required)
      - `imported_rows` (number, required)
    - `reached` (object, required)
      - `count` (number, required)
      - `outbound` (number, required)
      - `inbound` (number, required)
      - `overlap` (number, required)
      - `pct_of_called` (number, required, nullable)
    - `real_exchanges` (object, required)
      - `count` (number, required)
      - `pct_of_reached` (number, required, nullable)
    - `hot_leads` (object, required)
      - `count` (number, required)
      - `pct_of_reached` (number, required, nullable)
  - `effort` (object, required)
    - `calls_total` (number, required)
    - `outbound_attempts` (number, required)
    - `inbound_calls` (number, required)
  - `inbound` (object, required)
    - `unique_callers` (number, required)
  - `jump_in` (object, required)
    - `joined_calls` (number, required)
    - `median_time_to_join_seconds` (number, required, nullable)
    - `median_conversation_seconds` (number, required, nullable)
  - `outcome_breakdown` (array of object, required)
    - `outcome` (string, required)
    - `label` (string, required)
    - `count` (number, required)
  - `hot_lead_outcomes` (array of string, required)
  - `data_extraction` (object, required, nullable)
    - `intro` (string, required)
    - `fields` (array of string, required)
  - `leads` (object, required)
    - `interested` (array of object, required)
      - `name` (string, required)
      - `phone` (string, required)
      - `email` (string, required, nullable)
      - `direction` (enum (string), required): One of: `inbound`, `outbound`.
      - `summary` (string, required, nullable)
      - `last_activity_at` (any, required)
      - `call_id` (string, required)
      - `attempt_id` (string, required, nullable)
    - `callback_requested` (array of object, required)
      - `name` (string, required)
      - `phone` (string, required)
      - `email` (string, required, nullable)
      - `direction` (enum (string), required): One of: `inbound`, `outbound`.
      - `summary` (string, required, nullable)
      - `last_activity_at` (any, required)
      - `call_id` (string, required)
      - `attempt_id` (string, required, nullable)

#### 404: Not found in your organization

- `error` (string, required)

---

## Cancel a campaign

`POST https://www.getrevox.com/api/campaigns/{id}/cancel`

Cancel a running or scheduled campaign. Pending and queued calls will be aborted, while in-progress calls will be allowed to finish. Unlike deletion, the campaign and its rows are preserved for historical reference.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a/cancel \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 404: Not found in your organization

- `error` (string, required)

---

## Pause a running campaign

`POST https://www.getrevox.com/api/campaigns/{id}/pause`

Pause a running campaign so no further calls are placed. In-progress calls are allowed to finish; pending and scheduled calls are held until the campaign is resumed. Scheduled retry timers keep counting down, so a call resumed before its time fires on schedule, while one resumed after its time fires at the next available calling window.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a/pause \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `error` (string, required)

---

## Resume a paused campaign

`POST https://www.getrevox.com/api/campaigns/{id}/resume`

Resume a paused campaign. Held calls continue from where they left off; calls whose scheduled time passed during the pause are placed at the next available calling window.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X POST https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a/resume \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `error` (string, required)

---

## Export campaign rows

`GET https://www.getrevox.com/api/campaigns/{id}/export`

Export all rows of a campaign as a CSV file for offline analysis or reporting.

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X GET https://www.getrevox.com/api/campaigns/3c90c3cc-0d44-4b50-8888-8dd25736052a/export \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `csv` (string, required)
- `filename` (string, required)

#### 404: Not found in your organization

- `error` (string, required)

---

## Get voices

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

Retrieve all voices available for AI calls, including preset voices from Cartesia/ElevenLabs and your organization's cloned voices.

### Example request

```bash
curl -X GET https://www.getrevox.com/api/voices \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `voices` (array of [Voice](https://www.getrevox.com/docs/api/objects/voice.md), required)

---

## Get voice by ID

`GET https://www.getrevox.com/api/voices/{id}`

Retrieve details for a single voice by its unique ID and provider.

### Path parameters

- `id` (string, required): The voice ID to get.

### Query parameters

- `provider` (enum (string), required): One of: `cartesia`, `elevenlabs`, `gradium`.

### Example request

```bash
curl -X GET https://www.getrevox.com/api/voices/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `voice` (object, required)
  - `id` (string, required)
  - `name` (string, required)
  - `description` (string, optional)
  - `language` (enum (string), required): The language of the voice. One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Delete a voice

`DELETE https://www.getrevox.com/api/voices/{id}`

Delete a cloned voice. Only cloned voices can be deleted. Returns 409 if the voice is in use by an assistant.

### Path parameters

- `id` (string, required): The cloned voice ID to delete.

### Example request

```bash
curl -X DELETE https://www.getrevox.com/api/voices/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 403: The API key's organization cannot access this resource

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 409: Conflict with the resource's current state

- `error` (string, required)
- `assistantIds` (array of string, required)

---

## Generate voice preview

`POST https://www.getrevox.com/api/voices/preview`

Generate a short audio preview for a given voice.

### Request body (JSON)

- `voiceId` (string, required): The voice ID to generate a preview for.
- `provider` (enum (string), required): The provider to use for the preview. One of: `cartesia`, `elevenlabs`, `gradium`.
- `text` (string, optional): Custom text for the preview. If omitted, a short default is used. Constraints: max length 2000.
- `assistantPrompt` (string, optional): Prompt of the assistant the voice is for. When `text` is omitted, the preview is a few lines that assistant would say on a call. Constraints: max length 100000.
- `speed` (number, optional): Speed for preview. Cartesia 0.6–1.5, ElevenLabs 0.7–1.2. Default 1.0. Constraints: min 0.6, max 1.5.
- `volume` (number, optional): Volume for Cartesia preview (0.5–2.0). Ignored for other providers. Constraints: min 0.5, max 2.
- `model` (enum (string), optional): Cartesia model for the preview. Defaults to sonic-3.6. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.

### Example request

```bash
curl -X POST https://www.getrevox.com/api/voices/preview \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceId": "string",
    "provider": "cartesia"
  }'
```

### Responses

#### 200: Success

#### 400: Invalid request: the body or a parameter failed validation

- `error` (string, required)

#### 500: Server error

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Clone a voice

`POST https://www.getrevox.com/api/voices/clone`

Clone a voice from an audio recording. Send audio as a base64-encoded string. The cloned voice will be available in GET /voices.

### Request body (JSON)

- `audio` (string, required): Base64-encoded audio data (max ~7.5MB decoded) Constraints: max length 10000000.
- `contentType` (enum (string), required): MIME type of the audio One of: `audio/webm`, `audio/wav`, `audio/mpeg`, `audio/ogg`, `audio/mp4`, `video/webm`.
- `name` (string, required): Name for the cloned voice Constraints: min length 1.
- `language` (enum (string), required): Language of the voice One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.

### Example request

```bash
curl -X POST https://www.getrevox.com/api/voices/clone \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio": "string",
    "contentType": "audio/webm",
    "name": "Appointment reminder",
    "language": "en"
  }'
```

### Responses

#### 201: Created

- `id` (string, required)
- `cartesiaVoiceId` (string, required)
- `name` (string, required)
- `language` (string, required)
- `createdAt` (string, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 401: Missing or invalid API key

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 502: HTTP 502

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

---

## Get phone numbers

`GET https://www.getrevox.com/api/phone-numbers`

### Example request

```bash
curl -X GET https://www.getrevox.com/api/phone-numbers \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `phone_numbers` (array of [PhoneNumber](https://www.getrevox.com/docs/api/objects/phone-number.md), required)

---

## Update a phone number

`PATCH https://www.getrevox.com/api/phone-numbers/{id}`

### Path parameters

- `id` (string, required)

### Request body (JSON)

- `label` (string, optional, nullable)
- `inbound_assistant_id` (string, optional, nullable)

### Example request

```bash
curl -X PATCH https://www.getrevox.com/api/phone-numbers/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Responses

#### 200: Success

- `phone_number` ([PhoneNumber](https://www.getrevox.com/docs/api/objects/phone-number.md), required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `error` (string, required)

---

## Delete a phone number

`DELETE https://www.getrevox.com/api/phone-numbers/{id}`

### Path parameters

- `id` (string, required)

### Example request

```bash
curl -X DELETE https://www.getrevox.com/api/phone-numbers/3c90c3cc-0d44-4b50-8888-8dd25736052a \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `success` (boolean, required)

#### 400: Invalid request: the body or a parameter failed validation

- `message` (string, optional)
- `error` (string, optional)
- `bodyErrors` (object, optional): The validation errors returned from the API.
  - `issues` (array of object, required)
    - `path` (array of one of, required)
      - One of, **string** (string)
      - One of, **number** (number)
    - `message` (string, required)
    - `code` (string, optional)

#### 404: Not found in your organization

- `error` (string, required)

---

## GET /users/me

`GET https://www.getrevox.com/api/users/me`

Get the current authenticated user.

### Example request

```bash
curl -X GET https://www.getrevox.com/api/users/me \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

### Responses

#### 200: Success

- `user` ([User](https://www.getrevox.com/docs/api/objects/user.md), required)

#### 401: Missing or invalid API key

- `error` (string, required)

---

## PATCH /users/me

`PATCH https://www.getrevox.com/api/users/me`

Update the current authenticated user.

### Request body (JSON)

- `has_completed_onboarding` (boolean, optional)

### Example request

```bash
curl -X PATCH https://www.getrevox.com/api/users/me \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Responses

#### 200: Success

- `user` ([User](https://www.getrevox.com/docs/api/objects/user.md), required)

#### 401: Missing or invalid API key

- `error` (string, required)

---

## The Assistant object

### Fields

- `id` (string, required)
- `type` (enum (string), required): One of: `standalone`, `multi-step`, `sub-assistant`.
- `position` (object, required, nullable)
  - `x` (number, required)
  - `y` (number, required)
- `start_step_name` (string, required, nullable)
- `prompt` (string, required)
- `post_call_prompt` (string, required, nullable)
- `first_sentence` (string, required, nullable)
- `first_sentence_mode` (enum (string), required): One of: `generated`, `static`, `none`.
- `end_of_call_sentence` (string, required, nullable)
- `voice` (object, required, nullable)
  - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
  - `id` (string, required): The ID of the voice. Constraints: min length 1.
  - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
  - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
  - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
- `voice_languages` (array of object, required, nullable): Extra languages for a multilingual assistant, each with its own voice. Null for a single-language assistant.
  - `language` (enum (string), required): The language contacts are called in with this voice. One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.
  - `voice` (object, required): The voice used for contacts whose language is this language.
    - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
    - `id` (string, required): The ID of the voice. Constraints: min length 1.
    - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
    - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
    - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
- `cartesia_dictionary_pronunciation_id` (string, required, nullable): Optional Cartesia pronunciation dictionary ID linked to this assistant.
- `llm_model` (one of, required)
  - One of, **Recommended** (object)
    - `type` (string (constant), required): The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.
  - One of, **Gpt41Priority** (object)
    - `type` (string (constant), required): OpenAI gpt-4.1 on the priority tier, with gpt-4.1-mini answering a turn when gpt-4.1 is slow to respond. No per-assistant configuration.
  - One of, **Realtime** (object)
    - `type` (string (constant), required): Use a model from Realtime.
    - `provider` (enum (string), required): The provider to use from Realtime. eg: openai, google. One of: `openai`, `google`.
    - `realtime_model_id` (string, required): The model ID to use from Realtime. eg: gpt-4.1
    - `realtime_voice_id` (string, optional): Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck). Constraints: min length 1.
- `webhook_url` (string, required, nullable): The webhook URL to call when the call is completed.
- `max_call_duration_secs` (number, required): The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.
- `max_duration_end_message` (string, required, nullable): Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If null, the call ends silently. Constraints: max length 150.
- `structured_output_config` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required, nullable): The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).
- `structured_output_prompt` (string, required, nullable): Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
- `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), required, nullable): Configuration for call retry behavior including time windows, delays, and max iterations.
- `background_sound` (enum (string), required, nullable): Ambient background sound to play during the call. null disables it. One of: `audio/office.ogg`, `audio/waves.m4a`.
- `background_sound_volume` (number, required): Volume of the ambient background sound (0 = silent, 1 = max). Constraints: min 0, max 1.
- `thinking_sound` (enum (string), required, nullable): Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null disables it. One of: `city-ambience.ogg`, `forest-ambience.ogg`, `office-ambience.ogg`, `crowded-room.ogg`, `keyboard-typing.ogg`, `keyboard-typing2.ogg`, `hold_music.ogg`.
- `thinking_sound_volume` (number, required): Volume of the thinking sound (0 = silent, 1 = max). Constraints: min 0, max 1.
- `thinking_sound_probability` (number, required): Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking. Constraints: min 0, max 1.
- `transfer_destinations` (array of object, required, nullable): Where calls can be transferred to when users ask to speak to a human. Null or empty when transfer is not configured.
  - `label` (string, required): Constraints: min length 1, max length 60.
  - `phone_number` (string, required)
- `human_transfer_mode` (enum (string), required, nullable): Warm or cold transfer when transfer_destinations is non-empty; null when transfer is not configured. One of: `warm`, `cold`.
- `warm_transfer_summary_instructions` (string, required, nullable): Warm transfer only: instructions for the supervisor handoff summary; null when not configured or cold transfer.
- `warm_transfer_voice_speed` (number, required, nullable): Warm transfer only: voice speed of the briefing to the human colleague; null when it follows voice.speed, not configured, or cold transfer. Constraints: min 0.6, max 1.5.
- `ivr_navigation_enabled` (boolean, required): Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.
- `voicemail_message` (string, required, nullable): If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.
- `stt_context` (object, required, nullable): Assistant-level speech-to-text context: structured `general` key/value pairs plus a list of domain `terms`. Prompt-derived context is merged in without replacing existing entries.
  - `general` (array of object, required): Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required): Constraints: min length 1.
  - `terms` (array of string, required): Default: `[]`.
- `stt_model` (enum (string), required): Transcriber (speech-to-text) model used for the assistant. One of: `stt-rt-v4`, `stt-rt-v5`.
- `stt_endpoint_sensitivity` (number, required, nullable): Soniox endpoint sensitivity override (-1 to 1). Null: the agent's default tuning.
- `stt_endpoint_latency_level` (integer, required, nullable): Soniox endpoint latency adjustment level override (0 to 3). Null: the agent's default tuning. Constraints: min -9007199254740991, max 9007199254740991.
- `stt_bvc_filter_enabled` (boolean, required): When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output.
- `krisp_viva_filter_enabled` (boolean, required): When true, the agent's noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony.
- `first_sentence_delay_ms` (integer, required): Delay in milliseconds before speaking the first sentence. Default: 400. Constraints: min -9007199254740991, max 9007199254740991.
- `calendars` (array of [AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md), required): The calendars the agent books meetings on during a call, each named by the handle the prompt mentions. Only the `ready` ones are offered to the agent.
- `calendly` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `connection_id` (string, required): The connection ID representing the link between your Calendly account and Revox.
  - `event_type_id` (string, required): The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5) Constraints: min length 1.
- `cal` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `connection_id` (string, required): The connection ID representing the link between your Cal.com account and Revox.
  - `event_type_id` (string, required): The Cal.com event type to schedule. (eg: 7081322) Constraints: min length 1.
- `google_calendar` (object, required, nullable): Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in `calendars`. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  - `calendar_id` (string, required): The Google calendar to book on. (eg: primary)
  - `time_zone` (string, required): The timezone of the opening hours. (eg: Europe/Paris)
  - `duration_minutes` (integer, required): Constraints: min 5, max 480. Default: `30`.
  - `days` (array of integer, required): The open days, 0 is Sunday. Default: `[1,2,3,4,5]`.
  - `start_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"09:00"`.
  - `end_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"18:00"`.
  - `google_meet` (boolean, required): Adds a Google Meet link to the meeting. Default: `true`.
  - `connection_id` (string, required): The connection ID representing the link between your Google account and Revox.
- `hubspot` (object, required, nullable)
  - `connection_id` (string, required): The Nango connection ID linking the org's HubSpot account to Revox.
  - `precall_lookup_enabled` (boolean, required): Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up. Default: `false`.
  - `meeting_links` (array of object, required): Scheduling pages the agent can book on during a call — typically one per sales rep plus a round-robin team page marked as the fallback. Default: `[]`.
    - `slug` (string, required): HubSpot scheduling page slug, as returned by the meeting-links API (e.g. 'julien-marchand'). Constraints: min length 1.
    - `label` (string, required): Name the agent recognises for this calendar (e.g. 'Julien Marchand'). Listed in the prompt and matched against what the caller asks for. Constraints: min length 1.
    - `duration_ms` (integer, required): Meeting duration in milliseconds, chosen among the durations the scheduling page offers (e.g. 1800000 for 30 minutes). Constraints: max 9007199254740991, > 0.
    - `is_fallback` (boolean, required): Marks the round-robin calendar the agent falls back to when the requested rep has no slot. At most one meeting link may set this.
    - `booking_url` (string, required, nullable): Public URL of the scheduling page (e.g. https://meetings-eu1.hubspot.com/julien). The agent books through the API and only texts this link to the caller when the booking fails and the call can receive an SMS. Null on calendars saved before this field existed. Default: `null`.
  - `post_call_sync` (object, optional): Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.
    - `enabled` (boolean, required): Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says. Default: `false`.
    - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties. Default: `[]`.
      - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
      - `hubspot_property` (string, required): Destination HubSpot contact property, by internal name (e.g. 'email', 'company', or a custom 'budget'). Constraints: min length 1.
- `slack` (object, required, nullable)
  - `connection_id` (string, required): The Nango connection ID linking the org's Slack workspace to Revox.
  - `channels` (array of object, required): The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
    - `id` (string, required): The Slack channel ID (e.g. 'C01234567').
    - `name` (string, optional, nullable): Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
- `teams` (object, required, nullable)
  - `connection_id` (string, required): The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.
  - `channels` (array of object, required): The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
    - `id` (string, required): The Microsoft Teams channel ID (e.g. '19:561fbdbb...@thread.tacv2').
    - `name` (string, optional, nullable): Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
    - `team_id` (string, required): The ID of the team the channel belongs to. Needed to post.
    - `team_name` (string, optional, nullable): Human-readable team name. Channel names repeat across teams (every team has a 'General'), so the team name is what tells two of them apart.
- `zoho` (object, required, nullable)
  - `connection_id` (string, required): The Nango connection ID linking the org's Zoho CRM account to Revox.
  - `module` (string, required): Zoho module the prospect record is upserted into (e.g. 'Leads' or 'Contacts'). Constraints: min length 1.
  - `log_call_activity` (boolean, required): When true, also log the call as a record in Zoho's Calls module (related to the upserted prospect via Who_Id).
  - `field_mapping` (array of object, required): Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.
    - `source` (string, required): Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name. Constraints: min length 1.
    - `zoho_field` (string, required): Destination Zoho field API name on the upserted record (e.g. 'Email', 'Company', or a custom 'Budget__c'). Constraints: min length 1.
  - `template` (string, optional, nullable): Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.
- `custom_tools` (array of object, required, nullable)
  - `name` (string, required): Unique tool name in lowercase_snake_case (e.g. check_inventory) Constraints: min length 1, pattern ^[a-z][a-z0-9_]*$.
  - `description` (string, required): Human-readable description of what the tool does, used by the LLM to decide when to call it Constraints: min length 1.
  - `method` (enum (string), required): HTTP method to use when calling the API endpoint One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
  - `url` (string, required): Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values Constraints: min length 1.
  - `headers` (array of object, required): HTTP headers to include in the request. Values support {{variable}} placeholders Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required)
  - `query_params` (array of object, required): Query string parameters appended to the URL. Values support {{variable}} placeholders Default: `[]`.
    - `key` (string, required): Constraints: min length 1.
    - `value` (string, required)
  - `body_template` (string, required, nullable): JSON body template for the request. Use quoted {{variable}} placeholders (e.g. "{{name}}") for dynamic values Default: `null`.
  - `input_schema` (array of [StructuredOutputField](https://www.getrevox.com/docs/api/objects/structured-output-field.md), required): Schema defining the parameters the LLM should extract from the conversation to pass to this tool
- `from_phone_number` (string, required, nullable): Override the default outbound phone number for calls placed with this assistant. When null, the organization's default phone number is used.
- `logo_url` (string, required, nullable): Public URL of the brand logo shown on the assistant's demo page. Null when unset.
- `precall_lookup_url` (string, required, nullable): URL fetched before an inbound call is answered to resolve the assistant's prompt variables. Null when no lookup is configured.
- `precall_lookup_headers` (array of object, required, nullable): HTTP headers sent with the pre-call lookup request. Null when none are configured.
  - `key` (string, required): Constraints: max length 200, pattern ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$.
  - `value` (string, required): Constraints: min length 1, max length 4000.
- `organization_id` (string, required)
- `name` (string, required)
- `is_realestate_assistant` (boolean, optional)
- `is_inbound_receptionist` (boolean, optional)
- `created_by` (object, optional, nullable): The user who created the assistant.
  - `id` (string, required): The database user id of the creator.
  - `email` (string, required)
  - `first_name` (string, required, nullable)
  - `last_name` (string, required, nullable)
- `created_at` (any, required)
- `updated_at` (any, required)

---

## The AssistantCalendar object

### Fields

- `id` (string, required)
- `assistant_id` (string, required)
- `handle` (string, required, nullable): How the prompt names this calendar, as @handle: the provider, then the connected account (e.g. google_calendar_aric_at_getrevox.com). Null until an account is connected, unique within the assistant, kept when it is disconnected. Constraints: max length 255.
- `provider` (enum (string), required): One of: `google-calendar`, `calendly`, `cal-com-oauth`.
- `status` (enum (string), required): One of: `not_connected`, `needs_setup`, `ready`.
- `connection` (one of, required, nullable): The connected account, on the calendar's provider. Null until one is connected.
  - One of, **provider: "google-calendar"** (object)
    - `provider` (string (constant), required)
    - `connection_id` (string, required)
    - `settings` (object, required, nullable)
      - `calendar_id` (string, required): The Google calendar to book on. (eg: primary)
      - `time_zone` (string, required): The timezone of the opening hours. (eg: Europe/Paris)
      - `duration_minutes` (integer, required): Constraints: min 5, max 480. Default: `30`.
      - `days` (array of integer, required): The open days, 0 is Sunday. Default: `[1,2,3,4,5]`.
      - `start_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"09:00"`.
      - `end_time` (string, required): Constraints: pattern ^\d{2}:\d{2}$. Default: `"18:00"`.
      - `google_meet` (boolean, required): Adds a Google Meet link to the meeting. Default: `true`.
  - One of, **provider: "calendly"** (object)
    - `provider` (string (constant), required)
    - `connection_id` (string, required)
    - `settings` (object, required, nullable)
      - `event_type_id` (string, required): The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5) Constraints: min length 1.
  - One of, **provider: "cal-com-oauth"** (object)
    - `provider` (string (constant), required)
    - `connection_id` (string, required)
    - `settings` (object, required, nullable)
      - `event_type_id` (string, required): The Cal.com event type to schedule. (eg: 7081322) Constraints: min length 1.
- `account_label` (string, required, nullable): The connected account, usually its email. Null when not connected, or when the provider did not say.
- `connected_via_invite` (boolean, required): True when the account was connected by a colleague from the invite link.
- `invite` (object, required, nullable)
  - `url` (string, required, nullable): Page where a colleague without a Revox account connects their own calendar to this one. Anyone holding the link can, until it expires. Only given by the calendar endpoints, null on a calendar listed in an assistant.
  - `status` (enum (string), required): One of: `pending`, `completed`, `expired`.
  - `created_at` (any, required)
  - `expires_at` (any, required)
- `created_at` (any, required)

---

## The AssistantSetupIssue object

### Fields

- `message` (string, required): What is wrong, in the requested locale.
- `fix` (one of, required, nullable): The edit that fixes the issue, or null when none is known.
  - One of, **type: "text"** (object)
    - `type` (string (constant), required)
    - `field` (enum (string), required): The assistant field to edit. One of: `prompt`, `first_sentence`, `voicemail_message`, `end_of_call_sentence`.
    - `find` (string, required): Text that occurs exactly once in that field.
    - `replace` (string, required): Its replacement.
  - One of, **type: "voice"** (object)
    - `type` (string (constant), required)
    - `voice` (object, required): The voice to switch the assistant to.
      - `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
      - `id` (string, required): The ID of the voice. Constraints: min length 1.
      - `speed` (number, optional): The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0. Constraints: min 0.6, max 1.5.
      - `volume` (number, optional): Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers. Constraints: min 0.5, max 2.
      - `model` (enum (string), optional): Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers. One of: `sonic-3`, `sonic-3.5`, `sonic-3.6`.
    - `name` (string, required): That voice's name.

---

## The Call object

This represent a call "order" that was requested by the user. A call order can be resolved over multiple call attempts spanning up to a few days.

### Fields

- `id` (string, required): The ID of the call.
- `organization_id` (string, required): The ID of the organization that owns the call.
- `from_phone_number` (string, required): The phone number that made the call. Formatted in E.164 format. Example: +1234567890
- `to_phone_number` (string, required): The phone number that received the call. Formatted in E.164 format. Example: +1234567890
- `direction` (enum (string), required): Whether the call is inbound or outbound. One of: `inbound`, `outbound`.
- `channel` (enum (string), required): `web` for a test call taken in the browser: its phone number is a placeholder, never dialed. One of: `phone`, `web`.
- `status` (enum (string), required): The status of the call. One of: `initializing`, `queued_for_calling`, `calling`, `post_processing`, `not_launched`, `scheduled`, `paused`, `completed`, `cancelled`, `errored`.
- `is_completed` (boolean, required): DEPRECATED: Whether the call has completed. This is derived from `status`. Use `status` instead. Default: `false`.
- `is_cancelled` (boolean, required): DEPRECATED: Whether the call has been cancelled. This is derived from `status`. Use `status` instead. Default: `false`.
- `cancel_reason` (string (constant), optional, nullable): Why the call was cancelled, when it can be told. `prospect_called_back`: the prospect called back before the next retry, so the pending retry was cancelled and their call is recorded as a separate inbound call. Null for a manual or campaign cancel, and for calls that are not cancelled.
- `retries_stopped` (boolean, required): Whether no further attempt will be made for this call: it was cancelled, or its future attempts were stopped while an attempt was already in progress (that attempt still finishes). Unlike `is_cancelled`, this is true as soon as retries are stopped, before the call reaches a terminal status. Default: `false`.
- `callback_from` (object, optional, nullable): For an inbound call only: the outbound call this one answers, when the prospect rang us back after we called them. Null for every other call.
  - `call_id` (string, required)
  - `created_at` (any, required)
- `calls_count` (number, required): The number of call attempts made.
- `last_call_attempt` ([CallAttempt](https://www.getrevox.com/docs/api/objects/call-attempt.md), required, nullable)
- `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), required, nullable)
- `llm_model` (one of, required)
  - One of, **Option 1** (one of)
    - One of, **Recommended** (object)
      - `type` (string (constant), required): The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.
    - One of, **Gpt41Priority** (object)
      - `type` (string (constant), required): OpenAI gpt-4.1 on the priority tier, with gpt-4.1-mini answering a turn when gpt-4.1 is slow to respond. No per-assistant configuration.
    - One of, **Realtime** (object)
      - `type` (string (constant), required): Use a model from Realtime.
      - `provider` (enum (string), required): The provider to use from Realtime. eg: openai, google. One of: `openai`, `google`.
      - `realtime_model_id` (string, required): The model ID to use from Realtime. eg: gpt-4.1
      - `realtime_voice_id` (string, optional): Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck). Constraints: min length 1.
  - One of, **Legacy** (object)
    - `type` (enum (string), required): One of: `dedicated-instance`, `fireworks`, `openrouter`, `custom`, `gemma-4-31b-racing`.
- `call_attempts` (array of [CallAttempt](https://www.getrevox.com/docs/api/objects/call-attempt.md), required): All call attempts for this call order, ordered by most recent first.
- `assistant` ([Assistant](https://www.getrevox.com/docs/api/objects/assistant.md), required, nullable)
- `prompt_version` (object, optional, nullable): The assistant prompt version the call's prompt was compiled from. Null for calls created before versions were tracked, and for calls made with an inline assistant.
  - `id` (string, required): The ID of the assistant prompt version.
  - `number` (integer, required): The version's number in the assistant's prompt history (v1 is the oldest). Constraints: min -9007199254740991, max 9007199254740991.
  - `latest_number` (integer, required): The number of the assistant's current prompt version. Higher than `number` when the call was left on an older version, e.g. because it lacks a variable the newer prompt uses. Constraints: min -9007199254740991, max 9007199254740991.
- `campaign` (object, required, nullable)
  - `id` (string, required)
  - `name` (string, required)
  - `status` (enum (string), required): One of: `running`, `paused`, `completed`.
- `scheduled_at` (any, required, nullable): The time the call order is scheduled to start.
- `created_at` (any, required): The time the call order was created.
- `updated_at` (any, required): The time the call order was last updated (any state change, retry, or analysis result).
- `metadata` (map of string, required, nullable): Metadata stored with the call.
- `prompt_variables` (map of string, required, nullable): Variables used to interpolate the prompt.
- `transfer_destinations` (array of object, required, nullable): Where this call can be transferred, if anywhere.
  - `label` (string, required): Constraints: min length 1, max length 60.
  - `phone_number` (string, required)
- `contact` (object, required): Magic contact variables (prospect identity) extracted from the call's input data and transcript.
  - `first_name` (string, required, nullable)
  - `last_name` (string, required, nullable)
  - `email` (string, required, nullable)
  - `company` (string, required, nullable)
  - `job_title` (string, required, nullable)
- `first_sentence_delay_ms` (integer, required): Delay in milliseconds before speaking the first sentence. Default: 400. Constraints: min -9007199254740991, max 9007199254740991.
- `visual_number` (integer, optional, nullable): Campaign-scoped display number for the call ("#14" on the live campaign board), assigned when a human answers. Null outside campaigns or before a human picked up. Gaps are normal. Constraints: min -9007199254740991, max 9007199254740991.
- `outcome` (enum (string), optional, nullable): Business outcome of the call. Null if not computed or no transcript. One of: `not_interested`, `interested`, `completed`, `requested_callback_later`.
- `outcome_summary` (string, optional, nullable): LLM explanation for the outcome, when outcome was computed from the transcript.
- `do_not_call` (boolean, optional): True when the prospect's phone number is on the do-not-call list: it can no longer be called.
- `assignee` (object, required, nullable): The team member assigned to follow up on this call. Null when unassigned.
  - `id` (string, required): The database user id of the assignee.
  - `email` (string, required)
  - `first_name` (string, required, nullable)
  - `last_name` (string, required, nullable)

---

## The CallAttempt object

This represent a single call attempt. A call attempt is a single call made to the phone number.

### Fields

- `id` (string, required): The ID of the call attempt.
- `phone_number` (string, required): The phone number that was called. Formatted in E.164 format. Example: +1234567890
- `status` (enum (string), required): The status of the call attempt. One of: `queued`, `ringing`, `ongoing`, `completed`, `error`.
- `dial_error` (enum (string), required, nullable): The SIP error that occurred. One of: `number_non_attributed`, `too_many_calls`, `busy`, `temporarily_unavailable`, `no_answer`, `rejected`, `blocked`, `no_international_permission`, `precondition_failed`, `non_classified_error`.
- `result` (enum (string), required, nullable): One of: `IVR`, `voicemail`, `human`, `unknown`, `screening-filter`.
- `recording_url` (string, required, nullable): The URL of the audio recording of the call.
- `started_at` (any, required): The time the call started.
- `answered_at` (any, required): The time the call was answered.
- `ended_at` (any, required): The time the call ended.
- `transcript` (array of object, optional, nullable): The live transcript of the call, built in real time.
  - `role` (enum (string), required): One of: `user`, `assistant`, `human_agent`, `tool`.
  - `content` (string, required)
  - `tool_name` (string, optional)
  - `tool_arguments` (one of, optional)
    - One of, **Option 1** (map of any)
    - One of, **string** (string)
  - `tool_output` (string, optional)
  - `tool_is_error` (boolean, optional)
- `post_call_transcript` (array of object, optional, nullable): Higher-quality transcript generated after the call via Soniox async STT. Null until generated or when no recording is available.
  - `role` (enum (string), required): One of: `user`, `assistant`, `human_agent`, `tool`.
  - `content` (string, required)
  - `tool_name` (string, optional)
  - `tool_arguments` (one of, optional)
    - One of, **Option 1** (map of any)
    - One of, **string** (string)
  - `tool_output` (string, optional)
  - `tool_is_error` (boolean, optional)
- `structured_output` (map of any, optional, nullable): The data extracted from the call, using the structured output config from the parent call object.
- `assistants_used` (array of string, optional, nullable): Assistant node ids entered during this attempt, in traversal order.
- `assistant_names` (map of string, optional): Names of the assistants in `assistants_used`, keyed by id. Only set when the attempt went through several assistants (a multi-step call).
- `ended_by` (enum (string), optional, nullable): Who ended the call: 'agent' (AI agent), 'user' (caller/callee hung up), or 'system' (e.g. max duration limit). One of: `agent`, `user`, `system`.
- `end_reason` (enum (string), optional, nullable): Reason for ending the call when ended_by is 'agent'. E.g. 'tool_end_call', 'voicemail', 'transfer', 'ivr_no_navigate'. One of: `client_initiated`, `connection_timeout`, `human_takeover`, `ivr_no_navigate`, `max_duration`, `participant_removed`, `sip_trunk_failure`, `tool_end_call`, `transfer`, `user_inactive`, `user_rejected`, `user_unavailable`, `voicemail`, `speed_dial_abandoned`, `speed_dial_operator_missed`, `speed_dial_timeout`, `speed_dial_hangup`.
- `transferred_to` (string, optional, nullable): The number the call was transferred to, in E.164 format (e.g. +33123456789). Recorded by the agent from the destination it actually dialled, so it is the destination itself and not a name read off the transcript. Null when the call was not transferred, and on transfers placed before this was tracked.
- `handled_by_human` (boolean, required): Whether a human conducted (part of) this attempt — a jump-in / speed-dial takeover, or a transfer to a rep.
- `handled_by_ai` (boolean, required): Whether the AI agent conducted the conversation on this attempt. False for a silent speed-dial probe (whose agent only detects a human) and for attempts that were never answered.
- `handled_by_user` (object, required, nullable): The human operator (sales rep) who took over this attempt — jump-in takeover or speed-dial operator connection. Null for AI-only attempts and for takeovers recorded before this was tracked (fall back to a generic 'human' label).
  - `id` (string, required): The database user id of the assignee.
  - `email` (string, required)
  - `first_name` (string, required, nullable)
  - `last_name` (string, required, nullable)
- `sms_log` (array of object, optional, nullable): Automatic SMS sent after the call (voicemail and after-call), ordered oldest first. The in-call `send_sms` is excluded — it already appears in the transcript as a tool call.
  - `id` (string, required)
  - `type` (enum (string), required): One of: `in_call`, `voicemail`, `after_call`.
  - `to_phone_number` (string, required)
  - `message_body` (string, required)
  - `provider` (enum (string), required): One of: `twilio`, `vonage`.
  - `provider_message_id` (string, required, nullable)
  - `provider_status` (string, required, nullable): Delivery status in the provider's own vocabulary (Twilio queued/sent/delivered/failed/undelivered), so only interpretable alongside `provider`. Null when the provider hasn't reported one — always the case for Vonage, whose receipts we don't yet parse.
  - `provider_error_code` (string, required, nullable): The provider's numeric reason for a terminal failure (e.g. Twilio 30034). Null unless the message failed.
  - `created_at` (any, required): When the SMS was sent.
- `actions` (array of object, optional, nullable): Tools the agent ran for this attempt, in call and after it, ordered oldest first. This is the decision trail — the delivery trail lives in `sms_log` / `email_log`.
  - `id` (string, required)
  - `phase` (enum (string), required): One of: `in_call`, `post_call`.
  - `tool_name` (string, required)
  - `arguments` (map of any, required)
  - `status` (enum (string), required): One of: `succeeded`, `failed`.
  - `error` (string, required, nullable)
  - `created_at` (any, required): When the tool ran.
- `email_log` (array of object, optional, nullable): Notification emails sent in connection with the call, ordered oldest first (from/to addresses, subject, sent time).
  - `id` (string, required)
  - `from_address` (string, required)
  - `to_emails` (array of string, required)
  - `subject` (string, required)
  - `resend_message_id` (string, required, nullable)
  - `calendar_invite_at` (any, required, nullable): Start of the callback or meeting the attached calendar invitation (`invite.ics`) was for. Null when the email carried no invitation.
  - `created_at` (any, required): When the email was sent.
- `speech_events` (array of [CallSpeechEvent](https://www.getrevox.com/docs/api/objects/call-speech-event.md), optional, nullable): Per-turn speech segments (VAD-derived) with timing and pipeline latencies, ordered by started_speaking_at_ms. Empty for calls recorded before this was tracked or for realtime sessions that don't emit them.

---

## The CallRetryConfig object

Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.

### Fields

- `timezone` (string, optional, nullable): IANA timezone in which the calling windows and allowed days are evaluated, for every callee. Examples: 'Europe/Paris', 'America/New_York'. Null or omitted (the default): each callee's own timezone, derived from the country of their phone number (a French number → Europe/Paris, a UK number → Europe/London, a US number → America/Chicago). One timezone per country, so all US numbers share that one: set a timezone to call them on another. The agent also uses this timezone for the dates and times it talks about during the call.
- `calling_windows` (array of object, required)
  - `calling_window_start_time` (string, required): Start time of the calling window, in `timezone` (each callee's own timezone when it is null). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '09:00', '10am'. Default: '10:00'.
  - `calling_window_end_time` (string, required): End time of the calling window, in `timezone` (each callee's own timezone when it is null). Must be after the start time: a window cannot span midnight. Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '17:00', '6pm'. Default: '18:00'.
  - `retry_delay_seconds` (any, required): Delay between retry attempts in seconds. Values below the 15-minute minimum are raised to it: a shorter delay means calling someone again minutes after they declined. For one deliberate immediate second dial, use call_twice_in_a_row. Default: 7200 (2 hours).
- `max_retry_attempts` (integer, required): Maximum number of call attempts, first call included. Default: 5. Capped by the organization's plan: 5 on Starter, 8 on Business. A contact nobody picks up is billed once all its attempts were placed. Constraints: max 9007199254740991, > 0. Default: `5`.
- `allowed_days` (array of enum (string), required): Days of the week when calls are allowed, in the same timezone as the calling windows. Default: Monday through Friday. Default: `["monday","tuesday","wednesday","thursday","friday"]`.
- `call_twice_in_a_row` (boolean, required): Double call. If true and max_retry_attempts >= 2, when the first attempt reaches nobody (no answer, declined, voicemail, call screening nobody took), the second attempt is dialed within seconds instead of after retry_delay_seconds, from the same caller number. Two calls in a row from one number raise the pickup rate. Each call is an attempt: the double call counts as 2 when both calls happen, 1 when the first is picked up. Busy or unreachable phones are retried after the normal delay. Calling days and hours still apply. Only the first attempt is doubled; later ones follow retry_delay_seconds. A voicemail_message is left on the second dial only. Default: false. Default: `false`.

---

## The CallSpeechEvent object

### Fields

- `id` (string, required)
- `speaker` (enum (string), required): Who was speaking during this segment. One of: `user`, `agent`.
- `started_speaking_at_ms` (number, required): Milliseconds since session start when speech began.
- `stopped_speaking_at_ms` (number, required, nullable): Milliseconds since session start when speech ended. Null when the session ended before the turn closed.
- `transcript` (string, required, nullable): Recognized text for this segment, when available.
- `was_cut` (boolean, required, nullable): Agent-only: true when the agent's audio was interrupted (real or auto-resumed). Null on user segments.
- `is_real_turn` (boolean, required): False when the segment was flagged as noise/blip rather than a meaningful turn.
- `stt_transcription_delay_ms` (number, required, nullable): User-only: time from end-of-speech to final transcript, in ms.
- `llm_ttft_ms` (number, required, nullable): Agent-only: LLM time-to-first-token for the reply, in ms.
- `tts_ttfb_ms` (number, required, nullable): Agent-only: TTS time-to-first-audio-byte for the reply, in ms.
- `llm_winner_model` (string, required, nullable): Agent-only: the model that produced the reply — the winning leg when the LLM is a race, which is also the model `llm_ttft_ms` describes.
- `llm_system_prompt` (string, required, nullable): Agent-only: despite the name, the whole prompt the LLM was given for this turn — system instructions plus conversation history — as JSON.

---

## The Campaign object

### Fields

- `id` (string, required)
- `organization_id` (string, required)
- `name` (string, required)
- `assistant_id` (string, required)
- `assistant` ([Assistant](https://www.getrevox.com/docs/api/objects/assistant.md), optional)
- `from_phone_number` (string, optional, nullable)
- `max_concurrent_calls` (number, optional, nullable)
- `scheduled_at` (any, optional, nullable)
- `call_retry_config` ([CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md), optional, nullable)
- `status` (enum (string), required): One of: `running`, `paused`, `completed`.
- `is_cancelled` (boolean, required)
- `structured_output_extraction` (enum (string), optional): The status of the structured output extraction. One of: `none`, `running`, `completed`.
- `row_stats` (object, optional)
  - `not_launched` (number, required)
  - `skipped` (number, required)
  - `pending` (number, required)
  - `calling` (number, required)
  - `retry` (number, required)
  - `completed` (number, required)
  - `failed` (number, required)
  - `total` (number, required)
- `metadata_keys` (array of string, optional)
- `funnel_stats` (object, optional)
  - `total_leads` (number, required)
  - `hot` (number, required)
  - `talked_to_human` (number, required)
- `created_by` ([OrgMember](https://www.getrevox.com/docs/api/objects/org-member.md), optional, nullable)
- `created_at` (any, required)
- `updated_at` (any, required)

---

## The OrgMember object

A member of the current organization.

### Fields

- `id` (string, required): The database user id (foreign key target on calls.assignee_id).
- `email` (string, required)
- `first_name` (string, required, nullable)
- `last_name` (string, required, nullable)

---

## The PhoneNumber object

### Fields

- `id` (string, required)
- `phone_number` (string, required)
- `label` (string, required, nullable)
- `provider` (enum (string), required): One of: `twilio`, `telnyx`, `sip`.
- `livekit_outbound_trunk_id` (string, required, nullable)
- `inbound_assistant` ([Assistant](https://www.getrevox.com/docs/api/objects/assistant.md), required, nullable)
- `source` (enum (string), required): One of: `user_imported`, `revox_provisioned`, `revox_purchased`.
- `type` (enum (string), required): One of: `owned_number`, `verified_caller_id`.
- `created_at` (any, required)
- `inbound_sip_uri` (string, required, nullable)
- `created_by` ([OrgMember](https://www.getrevox.com/docs/api/objects/org-member.md), required, nullable)
- `health_status` (enum (string), required): One of: `unknown`, `healthy`, `warning`, `burned`.
- `spam_score` (number, required, nullable)
- `health_checked_at` (any, required, nullable)

---

## The StructuredOutputField object

### Fields

- `name` (string, required): Constraints: min length 1.
- `type` (enum (string), required): One of: `string`, `number`, `boolean`, `enum`, `date`, `datetime`.
- `description` (string, optional)
- `required` (boolean, required): Default: `false`.
- `enum_options` (array of string, optional)

---

## The User object

The current authenticated user.

### Fields

- `id` (string, required): The unique identifier of the user.
- `email` (string, required): The email address of the user.
- `first_name` (string, required, nullable): The first name of the user.
- `last_name` (string, required, nullable): The last name of the user.
- `organization_id` (string, required): The ID of the organization the user belongs to.
- `organization_country` (string, optional, nullable): ISO 3166-1 alpha-2 country code of the organization (e.g. FR). Used as the default region when normalizing national-format phone numbers.
- `has_completed_onboarding` (boolean, required): Whether the user has completed the onboarding tutorial.
- `created_at` (any, required): The time the user was created.
- `updated_at` (any, required): The time the user was last updated.

---

## The Voice object

### Fields

- `provider` (enum (string), required): The provider of the voice. One of: `cartesia`, `elevenlabs`, `gradium`.
- `id` (string, required): The ID of the voice. Constraints: min length 1.
- `name` (string, required): The name of the voice.
- `description` (string, required): The description of the voice.
- `language` (enum (string), required): The language of the voice. One of: `en`, `fr`, `es`, `de`, `it`, `pt`, `ru`, `zh`.
- `accent` (string, optional): The accent/dialect of the voice (e.g. 'american', 'british', 'australian', 'quebec').
- `gender` (string, optional): The gender of the voice (e.g. 'male', 'female', 'neutral').
- `isCloned` (boolean, optional): Whether this is a cloned voice.
- `modelCompat` (enum (string), optional): Cartesia model compatibility. Used to filter the voice list by the selected model. Absent/undefined is treated as 'universal'. One of: `universal`, `sonic-3`, `sonic-3.5`, `sonic-3.6`.