Skip to content

API reference

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 also exists in Markdown.

At a glance

Base URL
https://www.getrevox.com/api
Auth header
Authorization: Bearer $REVOX_API_KEY
Content type
application/json
OpenAPI 3.1
https://www.getrevox.com/openapi.json
For agents
https://www.getrevox.com/docs/api/llms.txt
MCP server
https://www.getrevox.com/api/mcp-servers/generic/mcp

Authentication

Every request carries an API key as a Bearer token: Authorization: Bearer YOUR_API_KEY. Create keys 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. Check an API key tells you whether a key works.

Quickstart: place a call and get its result

  1. 01

    Create an assistantPOST /assistants

    A name, a prompt and a voice: the voice's language is the language of the call. You can skip this step and send an inline assistant when you place the call.

    Request
    curl -X POST "https://www.getrevox.com/api/assistants" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminders",
    "prompt": "You are Julie, the assistant of the Acme dental practice. You call {{first_name}} to remind them of their appointment on {{appointment_date}} and ask them to confirm it. If they cannot come, offer to call them back to set a new date and ask when suits them best. Keep the call short and friendly.",
    "first_sentence": "Bonjour {{first_name}}, ici Julie du cabinet dentaire Acme. Je vous appelle au sujet de votre rendez-vous.",
    "first_sentence_mode": "static",
    "voice": {
      "provider": "cartesia",
      "id": "4325f426-c4e0-418e-a0e5-97fcdfcdf8e6"
    },
    "webhook_url": "https://example.com/webhooks/revox",
    "structured_output_config": [
      {
        "name": "appointment_confirmed",
        "type": "boolean",
        "description": "True when the person confirmed they will come.",
        "required": true
      },
      {
        "name": "preferred_callback_time",
        "type": "datetime",
        "description": "When the person wants to be called back to set a new date, if they asked to."
      }
    ]
  }'

    The French voice makes every call French, even with a prompt written in English. Each call sends first_name and appointment_date in prompt_variables; the extracted values come back in structured_output of each attempt, and the call is posted to webhook_url once it is over.

  2. 02

    Place the callPOST /call

    The phone_number in E.164 format and the assistant_id. prompt_variables fills the {{variables}} of the prompt for this contact. The response holds the call and its id right away: the call itself happens next.

    Request
    curl -X POST "https://www.getrevox.com/api/call" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+33612345678",
    "assistant_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
    "prompt_variables": {
      "first_name": "Marie",
      "appointment_date": "Thursday, November 12 at 10am"
    },
    "metadata": { "crm_id": "lead_48213" }
  }'

    Calls with the assistant of the Create an assistant example. prompt_variables fill its {{first_name}} and {{appointment_date}}; metadata comes back as sent on the call.

  3. 03

    Get the resultGET /call/{id}

    Poll the call every 5 to 10 seconds until its status is completed, cancelled or errored, or set the assistant's webhook_url and Revox POSTs the call to you (see Webhooks). Then read outcome and outcome_summary, and the latest attempt's transcript, recording and structured_output in last_call_attempt.

    Request
    curl -X GET "https://www.getrevox.com/api/call/8d2f6b1a-4c9e-4f37-b215-6a0e9c3d7f12" \
  -H "Authorization: Bearer $REVOX_API_KEY"

Calls and attempts

A call is an order that can take several attempts: when nobody answers, Revox calls back following the assistant's call_retry_config, inside its calling windows, sometimes over days. Each dial is an attempt in call_attempts. A call's final statuses are completed, cancelled or errored; a callee who asks to be called back at a given time sends the call back to scheduled when attempts are left.

To call a list, create a campaign with an assistant and its contacts (nothing is dialed yet), then launch its calls. Revox paces them (max_concurrent_calls), respects calling windows and retries, and keeps the campaign's statistics.

Conventions

  • Revox IDs (calls, assistants, campaigns…) are UUIDs; a voice id is its provider's. Phone numbers are E.164: +33612345678.
  • Timestamps are ISO 8601 in UTC. Send them ending in Z (2026-11-09T08:30:00Z): offsets such as +01:00 are rejected.
  • Field names are snake_case, except a few camelCase ones (in the voice endpoints, and unpatchedCallsNotice), written as each page shows them.
  • Unknown body fields are ignored without an error: copy field names from the pages.
  • Endpoints that say "No body" take none: send the request without one.
  • Use https://www.getrevox.com/api: getrevox.com answers with a 301 redirect, which most HTTP clients replay as a GET.

Errors

Errors use standard status codes. Their JSON body carries error (a message), except validation failures and unexpected errors, which carry message:

  • 400: a field or parameter failed validation: message: "Request validation failed" and bodyErrors.issues (or queryParameterErrors.issues), each with the path of the field and a message. A request the API understands but refuses (an empty campaign name, nothing to launch, a call that cannot be paused now) is also a 400, with error.
  • 401: the API key is missing or invalid.
  • 402: the organization has run out of credits (code: "INSUFFICIENT_BALANCE").
  • 403: the resource belongs to another organization.
  • 404: the resource does not exist in your organization.
  • 409: the resource's state forbids it, for example cancelling a finished call.
  • 500: unexpected server error, {"message": "Server Error"}. Retry later.
  • 502: a provider Revox relies on failed (voice cloning). Retry later.

SDKs

Official SDKs, generated from this API, may lag behind this reference:

Shell
npm install @revoxai/sdk   # TypeScript
pip install revox          # Python
gem install revox          # Ruby

For AI agents

  • If your client speaks MCP, the MCP server covers the main workflow as tools (assistants, voices, calendars, single calls and their results), guides prompt writing and can wait for a call to finish. Running campaigns (it can only list them), phone numbers, exports and voice cloning are REST only.
  • Every page exists in Markdown: add .md to its URL, or send Accept: text/markdown. llms.txt indexes them with recipes; llms-full.txt has everything in one file.
  • Field descriptions are the source of truth: they say what null and an omitted field mean when the two differ, and the "Before you call" box of an endpoint lists the rules the schema cannot express.

Reference