Browse the API reference

API reference

Revox API

View as Markdown

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, the index at https://www.getrevox.com/docs/api/llms.txt, and the OpenAPI 3.1 document at https://www.getrevox.com/openapi.json.

Base URL

Code
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:

Code
Authorization: Bearer YOUR_API_KEY

Create a key in the dashboard, under 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 tells you whether a key is valid.

Quickstart: place a call and get its result

  1. Create an assistant with POST /assistants: 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: 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} 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).

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 with an assistant and its contacts, then launch its calls. Revox paces them (max_concurrent_calls), respects calling windows and retries, and keeps per-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 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.
  • Field descriptions are the source of truth: they say what null and an omitted field mean when the two differ.

Reference