Get assistant by ID

GET/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.

Request

curl -X GET "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34" \
  -H "Authorization: Bearer $REVOX_API_KEY"

const res = await fetch("https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.REVOX_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
    headers={"Authorization": f"Bearer {os.environ['REVOX_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Try itSend this request live

Response

Success

{
  "id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
  "prompt": "You are Julie from Acme. You call {{first_name}} to confirm tomorrow's appointment.",
  "post_call_prompt": "Send the appointment address by SMS if asked.",
  "first_sentence": "Hello {{first_name}}, this is Julie from Acme.",
  "first_sentence_mode": "generated",
  "end_of_call_sentence": "Thank you, have a good day.",
  "voice": {
    "provider": "cartesia",
    "id": "4325f426-c4e0-418e-a0e5-97fcdfcdf8e6",
    "speed": 1,
    "volume": 1,
    "model": "sonic-3"
  },
  "voice_languages": [
    {
      "language": "en",
      "voice": {
        "provider": "cartesia",
        "id": "4325f426-c4e0-418e-a0e5-97fcdfcdf8e6",
        "speed": 1,
        "volume": 1,
        "model": "sonic-3"
      }
    }
  ],
  "cartesia_dictionary_pronunciation_id": "6f9a3c1e-2b7d-4e58-9a10-3d2c4b5e6f70",
  "llm_model": { "type": "recommended" },
  "webhook_url": "https://example.com/revox-webhook",
  "max_call_duration_secs": 600,
  "max_duration_end_message": "Thank you, have a good day.",
  "structured_output_config": [
    {
      "name": "budget",
      "type": "string",
      "description": "Books a slot in the agenda.",
      "required": false,
      "enum_options": ["enum option"]
    }
  ],
  "structured_output_prompt": "Send the appointment address by SMS if asked.",
  "call_retry_config": {
    "calling_windows": [
      {
        "calling_window_start_time": "09:00",
        "calling_window_end_time": "18:00",
        "retry_delay_seconds": 7200
      }
    ],
    "max_retry_attempts": 1,
    "allowed_days": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
    ],
    "excluded_dates": ["2026-11-05"],
    "call_twice_in_a_row": false
  },
  "timezone": "Europe/Paris",
  "background_sound": "audio/office.ogg",
  "background_sound_volume": 1,
  "thinking_sound": "city-ambience.ogg",
  "thinking_sound_volume": 1,
  "thinking_sound_probability": 0,
  "transfer_destinations": [
    { "label": "Main line", "phone_number": "+33612345678" }
  ],
  "human_transfer_mode": "warm",
  "warm_transfer_summary_instructions": "Send the appointment address by SMS if asked.",
  "warm_transfer_voice_speed": 1,
  "ivr_navigation_enabled": true,
  "voicemail_message": "Thank you, have a good day.",
  "stt_context": {
    "general": [{ "key": "crm_id", "value": "lead_8812" }],
    "terms": ["term"]
  },
  "stt_model": "stt-rt-v4",
  "first_sentence_delay_ms": 400,
  "calendars": [
    {
      "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
      "assistant_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
      "handle": "google_calendar_jane_at_example.com",
      "provider": "google-calendar",
      "status": "ready",
      "connection": {
        "provider": "google-calendar",
        "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
        "settings": {
          "calendar_id": "primary",
          "time_zone": "Europe/Paris",
          "duration_minutes": 30,
          "days": [1, 2, 3, 4, 5],
          "start_time": "09:00",
          "end_time": "18:00",
          "google_meet": false,
          "location": "{{site_address}}"
        }
      },
      "account_label": "Main line",
      "connected_via_invite": false,
      "invite": {
        "url": "https://example.com",
        "status": "completed",
        "created_at": "2026-11-05T09:00:00Z",
        "expires_at": "2026-11-05T09:00:00Z"
      },
      "created_at": "2026-11-05T09:00:00Z"
    }
  ],
  "calendly": null,
  "cal": null,
  "google_calendar": null,
  "hubspot": {
    "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "precall_lookup_enabled": true,
    "meeting_links": [
      {
        "slug": "jane-martin",
        "label": "Main line",
        "duration_ms": 1800000,
        "is_fallback": false,
        "booking_url": "https://example.com"
      }
    ],
    "post_call_sync": {
      "enabled": true,
      "field_mapping": [
        { "source": "email", "hubspot_property": "email" }
      ]
    }
  },
  "slack": {
    "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "channels": [
      {
        "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
        "name": "Appointment reminder"
      }
    ]
  },
  "teams": {
    "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "channels": [
      {
        "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
        "name": "Appointment reminder",
        "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "team_name": "Sales"
      }
    ]
  },
  "zoho": {
    "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "module": "Leads",
    "log_call_activity": false,
    "field_mapping": [
      { "source": "email", "zoho_field": "Email" }
    ],
    "template": "{{outcome}}: {{summary}}\n{{call_url}}"
  },
  "custom_tools": [
    {
      "name": "appointment_reminder",
      "description": "Books a slot in the agenda.",
      "method": "GET",
      "url": "https://example.com",
      "headers": [{ "key": "crm_id", "value": "lead_8812" }],
      "query_params": [
        { "key": "crm_id", "value": "lead_8812" }
      ],
      "body_template": "{\"email\": \"{{email}}\", \"name\": \"{{first_name}}\"}",
      "input_schema": [
        {
          "name": "budget",
          "type": "string",
          "description": "Books a slot in the agenda.",
          "required": false,
          "enum_options": ["enum option"]
        }
      ]
    }
  ],
  "from_phone_number": "+33187654321",
  "demo_page_url": "https://example.com",
  "precall_lookup_url": "https://example.com",
  "precall_lookup_headers": [
    { "key": "crm_id", "value": "lead_8812" }
  ],
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "Appointment reminders",
  "is_inbound_receptionist": false,
  "created_by": {
    "id": "5a7c9e1b-3d5f-4a2c-8e6b-0f1a2b3c4d5e",
    "email": "jane@example.com",
    "first_name": "Marie",
    "last_name": "Martin"
  },
  "created_at": "2026-11-05T09:00:00Z",
  "updated_at": "2026-11-05T09:02:41Z"
}

Path parameters

idstringrequired
ID of the assistant, as returned by GET /assistants.

Request body

No body: send the request without one.

Response

200

idstring
Unique ID of the assistant (UUID). Pass it as assistant_id to place a call or create a campaign with this assistant.
Example "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34"
promptstring
System prompt given to the LLM for the whole call: who the agent is, its goal and how to run the conversation. May contain {{variable}} placeholders, filled from the call's prompt_variables.
post_call_promptstringnullable
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_sentencestringnullable
The agent's opening line, spoken word for word. Only used, and only kept, with first_sentence_mode 'static': with 'generated' or 'none' it is dropped and reads back empty. May contain {{variable}} placeholders; one without a value is left out.
first_sentence_mode"generated" | "static" | "none"
How the agent opens the call. Default at creation: 'generated'.
"generated"
The agent opens with a greeting it writes from the prompt. first_sentence is not used, and not kept.
"static"
The agent opens with first_sentence, word for word.
"none"
The agent says nothing first and waits for the other person to speak.
end_of_call_sentencestringnullable
Sentence the agent says, without being interruptible, when it decides to end the call. Null or empty: the agent says a short default goodbye, only if it has not said goodbye already.
voiceobjectnullable
The voice the agent speaks with: provider, voice ID and speed. Its language (see GET /voices) is the language of the calls, unless voice_languages picks another one for a call. Always set on a saved assistant.
voice_languagesarray of objectnullable
Extra languages for a multilingual assistant, each with its own voice. Null for a single-language assistant.
cartesia_dictionary_pronunciation_idstringnullable
Optional Cartesia pronunciation dictionary ID linked to this assistant.
llm_modelobject
The LLM that drives the conversation. Defaults to recommended (the model Revox currently recommends for voice agents) when omitted at creation.
webhook_urlstringnullable
URL that receives a POST with the call and this assistant once the call is over, when it reaches completed or errored (not when it is cancelled). See Webhooks for the payload.
max_call_duration_secsnumber
Longest a call may last, in seconds: the agent then says max_duration_end_message, if set, and hangs up. Default at creation: 300. Outbound calls are capped at 600.
max_duration_end_messagestringnullable
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.
at most 150 characters
structured_output_configarray of StructuredOutputFieldnullable
The values to extract from each call (e.g. an email, a budget, a date). They land in structured_output of each call attempt, keyed by name.
structured_output_promptstringnullable
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_configCallRetryConfignullable
When and how often the assistant's calls are dialed. Null: the defaults.
timezonestring
IANA timezone of this assistant's calls, e.g. 'Europe/Paris' or 'America/Phoenix'. Every call runs in exactly one timezone: its calling windows and allowed days are read in it, the agent tells the date and offers calendar slots in it, and callbacks and extracted datetimes are interpreted in it. A campaign's timezone, then POST /call timezone, override it for their calls. Default when creating: 'Europe/Paris'. Replaces the deprecated call_retry_config.timezone.
background_sound"audio/office.ogg" | "audio/waves.m4a"nullable
Ambient background sound to play during the call. null disables it.
background_sound_volumenumber
Volume of the ambient background sound (0 = silent, 1 = max).
0 to 1
thinking_soundenum (7 values)nullable
Audio clip played while the agent prepares an answer. Null or omitted: none.
Possible values"city-ambience.ogg""forest-ambience.ogg""office-ambience.ogg""crowded-room.ogg""keyboard-typing.ogg""keyboard-typing2.ogg""hold_music.ogg"
thinking_sound_volumenumber
Volume of the thinking sound (0 = silent, 1 = max).
0 to 1
thinking_sound_probabilitynumber
Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking.
0 to 1
transfer_destinationsarray of objectnullable
Where calls can be transferred to when users ask to speak to a human. Null or empty when transfer is not configured.
human_transfer_mode"warm" | "cold"nullable
Warm or cold transfer when transfer_destinations is non-empty; null when transfer is not configured.
"warm"
The agent calls the destination first, briefs the person who answers on the call so far (see warm_transfer_summary_instructions), then puts the caller through.
"cold"
The call is passed on at once, without a briefing (a SIP REFER: the phone carrier must allow it).
warm_transfer_summary_instructionsstringnullable
Warm transfer only: instructions for the supervisor handoff summary; null when not configured or cold transfer.
warm_transfer_voice_speednumbernullable
Warm transfer only: voice speed of the briefing to the human colleague; null when it follows voice.speed, not configured, or cold transfer.
0.6 to 1.5
ivr_navigation_enabledboolean
Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.
voicemail_messagestringnullable
If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.
stt_contextobjectnullable
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.
first_sentence_delay_msinteger
Delay in milliseconds before speaking the first sentence. Default: 400.
calendarsarray of AssistantCalendar
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.
hubspotobjectnullable
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. Null when HubSpot is not connected.
slackobjectnullable
Slack config. When set, the post-call agent can post to the listed channels after a call; whether it posts, and what it says, is decided by post_call_prompt. Null when Slack is not connected.
teamsobjectnullable
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. Null when Teams is not connected.
zohoobjectnullable
Zoho CRM config. When set, the post-call agent can upsert the prospect (keyed on phone) into the chosen module and attach a Note with the call summary. Null when Zoho is not connected.
custom_toolsarray of objectnullable
Custom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution. Null or empty when the assistant has none.
from_phone_numberstringnullable
Caller ID of the calls placed with this assistant: a number of your organization (GET /phone-numbers), in E.164 format. A French mobile number (06, 07) cannot be the caller ID of an automated call. Null: a Revox number chosen for each destination.
demo_page_urlstringnullable
Public demo page of the assistant: anyone with this link can call the assistant and see the calls it placed, their transcripts and recordings. Null when the page is off. Turn it on, regenerate it or turn it off with POST /assistants/{id}/demo-page.
precall_lookup_urlstringnullable
URL fetched before an inbound call is answered to resolve the assistant's prompt variables. Null when no lookup is configured.
precall_lookup_headersarray of objectnullable
HTTP headers sent with the pre-call lookup request. Null when none are configured.
organization_idstring
ID of the organization that owns the assistant.
namestring
Display name of the assistant, shown in the dashboard and in call lists.
Example "Appointment reminders"
is_inbound_receptionistbooleanoptional
True when at least one of the organization's phone numbers sends its inbound calls to this assistant (see PATCH /phone-numbers/{id}, inbound_assistant_id). Not computed by every endpoint: absent or false does not prove that no number routes to it.
created_byobjectoptionalnullable
The user who created the assistant. Null for assistants created by Revox itself, for assistants created before this was tracked, and when that user was deleted.
created_atstring (date-time)
When the assistant was created (ISO 8601).
updated_atstring (date-time)
When the assistant was last modified (ISO 8601).