> Revox API docs for developers and AI agents. Index: https://www.getrevox.com/docs/api/llms.txt · Everything in one file: https://www.getrevox.com/docs/api/llms-full.txt · OpenAPI 3.1: https://www.getrevox.com/openapi.json · MCP server: https://www.getrevox.com/api/mcp-servers/generic/mcp
> Base URL https://www.getrevox.com/api · Auth: `Authorization: Bearer $REVOX_API_KEY`

# Search calls

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

Search your organization's calls, most recent activity first by default. Filters, page and page_size are JSON body fields, and every filter is optional. Each entry is a full call, with its attempts.

## Before you call

- Filters, `page` and `page_size` are JSON body fields, not query parameters. Every filter is optional: `{}` returns the 50 most recently updated calls.
- There is no date filter. To read the calls since a date, keep the default sort (`updated_at`, newest first) and stop paging once `updated_at` is older than your cutoff.
- Unknown body fields are ignored, not rejected: a misspelled filter returns unfiltered results.
- Values within one filter are combined with OR, different filters with AND, except `variables`, whose entries must all match.

## Request

The 20 most recently updated calls whose outcome is interested or requested_callback_later.

```bash
curl -X POST "https://www.getrevox.com/api/call/search" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outcomes": ["interested", "requested_callback_later"],
    "sort_by": "updated_at",
    "sort_direction": "desc",
    "page_size": 20
  }'
```

## Body

JSON.

- `query` (string, optional): Free-text search. A call matches when it contains every word of the query (3 characters or more, in any order) in its phone numbers, contact identity, metadata or prompt variable values, or in the extracted data of its last attempt. A phone number typed with spaces or a leading 0 is matched on its digits.
- `statuses` (array of enum (10 values), optional, default []): Keep calls in any of these statuses. A scheduled call of a paused campaign counts as 'paused'.
  - `"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`](https://www.getrevox.com/docs/api/campaigns/launch-a-campaigns-calls.md). 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`](https://www.getrevox.com/docs/api/calls/resume-a-paused-call.md), 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`](https://www.getrevox.com/docs/api/calls/cancel-a-call.md), 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.
- `directions` (array of ("inbound" | "outbound"), optional, default []): Keep calls in any of these directions.
  - `"inbound"`: Someone called one of your numbers and an assistant answered.
  - `"outbound"`: Revox called the number: from [`POST /call`](https://www.getrevox.com/docs/api/calls/place-a-call.md), a campaign or the dashboard.
- `results` (array of enum (6 values), optional, default []): Keep calls whose last attempt has one of these results (who answered: human, voicemail, IVR...). 'none' matches calls whose last attempt has no result yet, or no attempt at all.
  - `"IVR"`: An automated phone menu answered (e.g. 'press 1 for sales').
  - `"voicemail"`: A voicemail or an answering machine answered.
  - `"human"`: A person answered.
  - `"unknown"`: Silence, or audio that could not be classified.
  - `"screening-filter"`: A call screening assistant (Apple or Google) answered for the person and asked who is calling and why.
  - `"none"`: The last attempt has no result yet, or there is no attempt.
- `outcomes` (array of enum (6 values), optional, default []): Keep calls with one of these business outcomes. 'none' matches calls without an outcome, 'do_not_call' calls whose number is on the do-not-call list (those match no other outcome value).
  - `"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.
  - `"none"`: The call has no outcome.
  - `"do_not_call"`: The number is on the do-not-call list. Such a call matches no other outcome value.
- `assistant_ids` (array of string, optional, default []): Keep calls placed with one of these assistants. A step of a multi-step flow matches the calls that went through it. 'none' matches calls whose assistant was deleted.
- `campaign_ids` (array of string, optional, default []): Keep calls of one of these campaigns. With this filter, a call superseded by the prospect calling back is left out, so each contact is listed once.
- `from_phone_numbers` (array of string, optional, default []): Keep calls whose from_phone_number is one of these numbers (your number for an outbound call, the caller's for an inbound one), in E.164 format, exact match.
- `assignee_ids` (array of (string | "none"), optional, default []): Keep calls assigned to one of these team members (user IDs, see the call's assignee.id). 'none' matches unassigned calls.
- `variables` (array of object, optional): Keep calls whose metadata (or, when the metadata has no such key, prompt variables) hold all these values.
  - `variables.key` (string, required): Name of the metadata entry or prompt variable.
  - `variables.value` (string, required): Value it must have, compared case-insensitively and ignoring surrounding spaces.
- `to_phone_number` (string, optional): Keep calls whose to_phone_number is this number (the person called for an outbound call, your number for an inbound one), in E.164 format, exact match. Ignored by [`POST /call/export`](https://www.getrevox.com/docs/api/calls/export-calls-history.md).
- `call_ids` (array of string, optional): Keep only the calls with these IDs. Ignored by [`POST /call/export`](https://www.getrevox.com/docs/api/calls/export-calls-history.md).
- `page` (integer, optional, default 1): Page number, starting at 1. Default: 1. ≥ 1.
- `page_size` (integer, optional, default 50): Number of calls per page, 1 to 100. Default: 50.
- `sort_by` (string, optional): Sort order. 'updated_at' (the default): most recent activity. 'duration': talk time of the last attempt, calls without one last. 'priority': a fixed order for working a campaign (live calls, then calls a person from your team joined, hot leads, calls a person answered, queued, scheduled, the rest), which ignores sort_direction. 'structured_output.<field>': a value extracted from the last attempt.
- `sort_direction` ("asc" | "desc", optional): 'asc' or 'desc' (the default).

## Response 200

```json
{
  "calls": [
    {
      "id": "8d2f6b1a-4c9e-4f37-b215-6a0e9c3d7f12",
      "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "from_phone_number": "+33199001234",
      "to_phone_number": "+33612345678",
      "direction": "outbound",
      "channel": "phone",
      "status": "completed",
      "is_completed": true,
      "is_cancelled": false,
      "cancel_reason": null,
      "retries_stopped": false,
      "callback_from": null,
      "calls_count": 1,
      "last_call_attempt": {
        "id": "c41f9a2e-7d3b-4e85-a6f0-1b2c3d4e5f60",
        "phone_number": "+33612345678",
        "status": "completed",
        "dial_error": null,
        "result": "human",
        "recording_url": "https://recordings.example.com/7c9e6679-7425-40de-944b-e07fc1f90ae7.wav",
        "started_at": "2026-11-09T08:30:02Z",
        "answered_at": "2026-11-09T08:30:09Z",
        "ended_at": "2026-11-09T08:31:47Z",
        "transcript": [
          {
            "role": "assistant",
            "content": "Bonjour Marie, ici Julie du cabinet Acme. Je vous appelle pour confirmer votre rendez-vous de jeudi à 10 heures."
          },
          {
            "role": "user",
            "content": "Oui, c'est bien noté, merci."
          }
        ],
        "post_call_transcript": [
          {
            "role": "assistant",
            "content": "Bonjour Marie, ici Julie du cabinet Acme. Je vous appelle pour confirmer votre rendez-vous de jeudi à 10 heures."
          },
          {
            "role": "user",
            "content": "Oui, c'est bien noté, merci."
          }
        ],
        "structured_output": {
          "appointment_confirmed": true,
          "preferred_callback_time": null
        },
        "assistants_used": [
          "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
          "b7e2d4c9-1a3f-4e6b-8d5c-2f9a0c7e1b43"
        ],
        "assistant_names": {
          "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34": "Reception",
          "b7e2d4c9-1a3f-4e6b-8d5c-2f9a0c7e1b43": "Appointment booking"
        },
        "ended_by": "agent",
        "end_reason": "tool_end_call",
        "transferred_to": null,
        "handled_by_human": false,
        "handled_by_ai": true,
        "handled_by_user": null,
        "sms_log": [
          {
            "id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
            "type": "in_call",
            "to_phone_number": "+33612345678",
            "message_body": "Votre rendez-vous du jeudi 12 novembre à 10h au cabinet dentaire Acme est confirmé.",
            "provider": "twilio",
            "provider_message_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
            "provider_status": "delivered",
            "provider_error_code": null,
            "created_at": "2026-11-05T09:00:00Z"
          }
        ],
        "actions": [
          {
            "id": "d4c3b2a1-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
            "phase": "in_call",
            "tool_name": "send_sms",
            "arguments": {
              "message": "Votre rendez-vous du jeudi 12 novembre à 10h au cabinet dentaire Acme est confirmé."
            },
            "status": "succeeded",
            "error": null,
            "created_at": "2026-11-05T09:00:00Z"
          }
        ],
        "email_log": [
          {
            "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
            "from_address": "Appointment reminders <noreply@example.com>",
            "to_emails": ["jane@example.com"],
            "subject": "Your appointment tomorrow",
            "resend_message_id": "d4c3b2a1-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
            "calendar_invite_at": "2026-11-05T09:00:00Z",
            "created_at": "2026-11-05T09:00:00Z"
          }
        ]
      },
      "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
      },
      "llm_model": { "type": "recommended" },
      "call_attempts": [
        {
          "id": "c41f9a2e-7d3b-4e85-a6f0-1b2c3d4e5f60",
          "phone_number": "+33612345678",
          "status": "completed",
          "dial_error": null,
          "result": "human",
          "recording_url": "https://recordings.example.com/7c9e6679-7425-40de-944b-e07fc1f90ae7.wav",
          "started_at": "2026-11-09T08:30:02Z",
          "answered_at": "2026-11-09T08:30:09Z",
          "ended_at": "2026-11-09T08:31:47Z",
          "transcript": [
            {
              "role": "assistant",
              "content": "Bonjour Marie, ici Julie du cabinet Acme. Je vous appelle pour confirmer votre rendez-vous de jeudi à 10 heures."
            },
            {
              "role": "user",
              "content": "Oui, c'est bien noté, merci."
            }
          ],
          "post_call_transcript": [
            {
              "role": "assistant",
              "content": "Bonjour Marie, ici Julie du cabinet Acme. Je vous appelle pour confirmer votre rendez-vous de jeudi à 10 heures."
            },
            {
              "role": "user",
              "content": "Oui, c'est bien noté, merci."
            }
          ],
          "structured_output": {
            "appointment_confirmed": true,
            "preferred_callback_time": null
          },
          "assistants_used": [
            "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
            "b7e2d4c9-1a3f-4e6b-8d5c-2f9a0c7e1b43"
          ],
          "assistant_names": {
            "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34": "Reception",
            "b7e2d4c9-1a3f-4e6b-8d5c-2f9a0c7e1b43": "Appointment booking"
          },
          "ended_by": "agent",
          "end_reason": "tool_end_call",
          "transferred_to": null,
          "handled_by_human": false,
          "handled_by_ai": true,
          "handled_by_user": null,
          "sms_log": [
            {
              "id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
              "type": "in_call",
              "to_phone_number": "+33612345678",
              "message_body": "Votre rendez-vous du jeudi 12 novembre à 10h au cabinet dentaire Acme est confirmé.",
              "provider": "twilio",
              "provider_message_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
              "provider_status": "delivered",
              "provider_error_code": null,
              "created_at": "2026-11-05T09:00:00Z"
            }
          ],
          "actions": [
            {
              "id": "d4c3b2a1-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
              "phase": "in_call",
              "tool_name": "send_sms",
              "arguments": {
                "message": "Votre rendez-vous du jeudi 12 novembre à 10h au cabinet dentaire Acme est confirmé."
              },
              "status": "succeeded",
              "error": null,
              "created_at": "2026-11-05T09:00:00Z"
            }
          ],
          "email_log": [
            {
              "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
              "from_address": "Appointment reminders <noreply@example.com>",
              "to_emails": ["jane@example.com"],
              "subject": "Your appointment tomorrow",
              "resend_message_id": "d4c3b2a1-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
              "calendar_invite_at": "2026-11-05T09:00:00Z",
              "created_at": "2026-11-05T09:00:00Z"
            }
          ]
        }
      ],
      "assistant": {
        "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"
      },
      "prompt_version": {
        "id": "6f9a3c1e-2b7d-4e58-9a10-3d2c4b5e6f70",
        "number": 1,
        "latest_number": 1
      },
      "campaign": {
        "id": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b",
        "name": "Appointment reminder",
        "status": "completed"
      },
      "scheduled_at": "2026-11-09T08:30:00Z",
      "created_at": "2026-11-06T16:12:45Z",
      "updated_at": "2026-11-09T08:32:20Z",
      "metadata": { "crm_id": "lead_48213" },
      "prompt_variables": {
        "first_name": "Marie",
        "company": "Acme"
      },
      "transfer_destinations": [
        { "label": "Main line", "phone_number": "+33612345678" }
      ],
      "contact": {
        "first_name": "Marie",
        "last_name": "Martin",
        "email": "jane@example.com",
        "company": "Acme",
        "job_title": "Office manager"
      },
      "first_sentence_delay_ms": 400,
      "outcome": "interested",
      "outcome_summary": "Marie confirmed her appointment on Thursday at 10:00 and asked for the address by text message.",
      "do_not_call": false,
      "assignee": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "email": "jane@example.com",
        "first_name": "Marie",
        "last_name": "Martin"
      }
    }
  ],
  "total_count": 3
}
```

- `calls` (array of [Call](https://www.getrevox.com/docs/api/objects/call.md)): The calls of the requested page, in the requested order.
- `total_count` (number): Number of calls matching the filters, all pages together.

## Objects on this page

Defined on their own pages: [CallAttempt](https://www.getrevox.com/docs/api/objects/call-attempt.md) (One dial of a call's phone number, with what answered, the transcript, the recording and the extracted data.); [CallRetryConfig](https://www.getrevox.com/docs/api/objects/call-retry-config.md) (When and how often a call is dialed: the calling windows and allowed days, the delay between two attempts and the maximum number of attempts.); [Assistant](https://www.getrevox.com/docs/api/objects/assistant.md) (The voice agent that places and answers calls: its prompt, voice and LLM, how it opens and ends a call, the data it extracts, and the tools and calendars it uses.); [Call](https://www.getrevox.com/docs/api/objects/call.md) (One order to call one phone number with an assistant.).