Skip to content
Calls

Place a call

POST/call

Place an outbound call with a saved assistant (assistant_id) or a configuration for this call only (assistant). The call is dialed right away or at scheduled_at, inside the calling windows, and called back when nobody answers, as call_retry_config allows: it can take several days. The response comes back at once with the call; follow it with GET /call/{id} or the assistant's webhook_url.

Request body

  • phone_numberstringrequired

    The phone number to call, in E.164 format (e.g. +33612345678).

  • skip_calling_windowboolean

    Bypass the calling-window check for this call's first dial so it dials even outside the assistant's calling windows, allowed days and excluded_dates. Retries, if any, follow them again. Use for immediate 'call now' dials.

  • timezonestringnullable

    IANA timezone of this call, in place of its campaign's or assistant's timezone. Examples: 'America/Los_Angeles', 'Europe/Paris'. The call runs in exactly this 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. Omitted or null: the campaign's timezone, else the assistant's. It is never derived from the phone number.

  • from_phone_numberstring

    Caller ID of the call, in E.164 format: one of your organization's numbers (GET /phone-numbers). Omitted: the assistant's from_phone_number, or else a Revox number chosen for the destination.

  • call_twice_in_a_rowboolean

    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.

  • call_retry_configCallRetryConfigOverride
  • prompt_variablesobject<string, string>

    Values of the assistant's {{variables}} for this call, keyed by variable name, whether the call uses assistant_id or an inline assistant. Send every variable the prompt and first sentence use. A missing or empty one is not rejected: the prompt reads '(name: not provided)' in its place, and a static first sentence leaves it out.

    Keys: Variable name, as written between the braces: name for {{name}}.

  • metadataobject<string, string>

    Your own key/value pairs to store with the call, e.g. your CRM ID. They come back as sent on the call.

    Keys: A key of your choice.

  • assistant_idstring (uuid)

    ID of a saved assistant to place the call with (GET /assistants). Send it or assistant, not both.

  • assistantobject

    A configuration for this call only, when you do not use a saved assistant. Ignored when assistant_id is sent.

  • concurrencyobject

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

  • campaignobject

    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.

  • scheduled_atstring (date-time)

    When to place the call: ISO 8601 in UTC ending in Z, e.g. 2026-11-09T08:30:00Z; offsets such as +01:00 are rejected. Omitted: right away, or when the next calling window opens.

Response

200
  • callCall
    • idstring

      The ID of the call.

      Example "8d2f6b1a-4c9e-4f37-b215-6a0e9c3d7f12"

    • organization_idstring

      The ID of the organization that owns the call.

    • from_phone_numberstring

      The phone number that made the call (the caller ID of an outbound call), in E.164 format.

      Example "+33199001234"

    • to_phone_numberstring

      The phone number that received the call (the person called, for an outbound call), in E.164 format.

      Example "+33612345678"

    • direction"inbound" | "outbound"

      Whether Revox placed the call or received it.

      "inbound"

      Someone called one of your numbers and an assistant answered.

      "outbound"

      Revox called the number: from POST /call, a campaign or the dashboard.

    • channel"phone" | "web"

      Where the call takes place.

      "phone"

      A phone call.

      "web"

      A test call taken in the browser, from the dashboard: its phone number is a placeholder, never dialed.

    • statusenum (10 values)

      Where the call stands. Final statuses, after which nothing changes: completed, cancelled, errored.

      "initializing"

      Being created, not scheduled yet. Newer calls start as scheduled instead.

      "queued_for_calling"

      Its turn came: the attempt is about to dial, within your concurrent call limit.

      "calling"

      An attempt is in progress: the phone is ringing or a conversation is going on.

      "post_processing"

      The phone conversation is over; the transcript, outcome and extracted data are being computed. It can no longer be paused or cancelled.

      "not_launched"

      Created but never sent: a campaign call waiting for POST /campaigns/{id}/launch-calls. It is not dialed until then.

      "scheduled"

      Waiting to be dialed at scheduled_at (the first attempt, a retry or a requested callback). A call due outside its calling windows waits for the next one.

      "paused"

      No new attempt is made until it is resumed (POST /call/{id}/resume, or resuming its campaign).

      "completed"

      Final. Revox will not dial it again: a person or a phone menu answered, or the last attempt allowed by call_retry_config was made. outcome and last_call_attempt tell how it went.

      "cancelled"

      Final. Cancelled before it completed: by a user (POST /call/{id}/cancel, the dashboard, a campaign cancel), or because the prospect called back (see cancel_reason).

      "errored"

      Final. The call could not be placed and will not be retried: the number does not exist, the destination cannot be called, the organization ran out of credits, or an internal error stopped it.

    • cancel_reason"prospect_called_back"optionalnullable

      Why the call was cancelled, when it can be told. Null for a cancel by a user or a campaign, and for calls that are not cancelled.

      "prospect_called_back"

      The prospect called back before the next retry: the pending retry was cancelled, and their call is recorded as a separate inbound call.

    • retries_stoppedboolean

      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_fromobjectoptionalnullable

      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. A callback is matched on the caller's number against outbound calls dialed within the last 2 days on a shared Revox number, or within the last 30 days on a number dedicated to your organization (only your own calls are matched there), counted from the last attempt. A matched callback carries the outbound call's metadata over, cancels its pending retries, and is answered by the outbound call's assistant when the prospect dials back the number we called from (or when the number they dial has no inbound assistant), otherwise by that number's inbound assistant. Its end-of-call webhook goes to the webhook_url of the assistant that answers.

    • calls_countnumber

      The number of call attempts made.

      Example 1

    • last_call_attemptCallAttemptnullable

      The most recent attempt, the same as the first entry of call_attempts. Null until a first attempt is made.

    • call_retry_configCallRetryConfignullable

      Retry configuration this call follows: calling windows, allowed days, delay between attempts and maximum attempts. Copied when the call is created from the assistant's, or the campaign's for a campaign call, with the per-call overrides of POST /call (timezone, call_twice_in_a_row) applied.

    • llm_modelobject

      The LLM that drives this call, copied from the assistant when the call is created.

    • call_attemptsarray of CallAttempt

      All call attempts for this call order, ordered by most recent first.

    • assistantAssistantnullable

      The assistant the call was placed with, as it is configured now (not a snapshot taken at call time). Null for a call made with an inline assistant configuration, and when the assistant was deleted.

    • prompt_versionobjectoptionalnullable

      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.

    • campaignobjectnullable

      The campaign this call belongs to. Null for a call outside any campaign.

    • scheduled_atstring (date-time)nullable

      When the call's next attempt is due (ISO 8601): the requested start for a new call, then the time of the next retry. Null when no time is set, e.g. for a campaign call not launched yet.

      Example "2026-11-09T08:30:00Z"

    • created_atstring (date-time)

      When the call was created.

      Example "2026-11-06T16:12:45Z"

    • updated_atstring (date-time)

      When the call last changed: a status change, a new attempt or an analysis result. POST /call/search sorts on it by default.

      Example "2026-11-09T08:32:20Z"

    • metadataobject<string, string>nullable

      Your own key/value pairs stored with the call (e.g. your CRM ID), as sent in POST /call. On an inbound callback (callback_from set), the metadata of the outbound call it answers, copied over whichever assistant answers; null on other inbound calls. The query and variables filters of POST /call/search match them.

      Keys: A key of your choice.

    • prompt_variablesobject<string, string>nullable

      The values of the assistant's {{variables}} for this call, keyed by variable name.

      Keys: Variable name, as written between the braces: name for {{name}}.

    • transfer_destinationsarray of objectnullable

      Where this call can be transferred, if anywhere.

    • contactobject

      Who the prospect is, read from the call's prompt variables and, after the call, from the transcript.

    • first_sentence_delay_msinteger

      Delay in milliseconds before speaking the first sentence. Default: 400.

    • outcomeenum (4 values)optionalnullable

      How the call went for your business, set after the conversation. Null until computed, and when nobody talked.

      "not_interested"

      The person declined, refused or showed no interest.

      "interested"

      The person engaged and is a lead to follow up: the strongest outcome the AI assigns.

      "completed"

      A person from your team talked to the prospect: they joined the call, the call was transferred to them, or they set this outcome by hand. Never assigned by the AI.

      "requested_callback_later"

      The person asked to be called back later. When they gave a time and attempts are left, the call is scheduled again for that time.

    • outcome_summarystringoptionalnullable

      Why the call got its outcome, in a few sentences written from the transcript. Null when there is no outcome.

      Example "Marie confirmed her appointment on Thursday at 10:00 and asked for the address by text message."

    • do_not_callbooleanoptional

      True when the prospect's phone number is on the do-not-call list: it can no longer be called.

    • assigneeobjectnullable

      The team member assigned to follow up on this call. Null when unassigned.

Errors

  • 400Invalid request: a field or parameter failed validation{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }
  • 402Not enough credits on the organization{ "error": string, "code": "INSUFFICIENT_BALANCE" }
  • 404Not found in your organization{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }
  • 409Conflicts with the resource's current state{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }

Error bodies carry an error (or message) string; a 400 adds bodyErrors.issues. See Errors.