> 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/mcp
> Base URL https://www.getrevox.com/api · Auth: `Authorization: Bearer $REVOX_API_KEY`

# Check a phone number's spam reputation now

`POST https://www.getrevox.com/api/phone-numbers/{id}/reputation-check`

Runs a spam-reputation check of the number right away and returns the number with its new health_status, spam_score and health_checked_at. Numbers that place calls are already checked automatically; use this for a number never checked, or after a drop in answer rate. Once per number every 48 hours: before that, 429 with the number's next_manual_check_at.

## Request

```bash
curl -X POST "https://www.getrevox.com/api/phone-numbers/6f9a3c1e-2b7d-4e58-9a10-3d2c4b5e6f70/reputation-check" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Path parameters

- `id` (string, required): ID of the phone number record, as returned by [`GET /phone-numbers`](https://www.getrevox.com/docs/api/phone-numbers/get-phone-numbers.md) (not the phone number itself).

## Body

JSON.

An empty object: send `{}` or no body at all.

## Response 200

```json
{
  "phone_number": {
    "id": "6f9a3c1e-2b7d-4e58-9a10-3d2c4b5e6f70",
    "phone_number": "+33199001234",
    "label": "Main line",
    "provider": "twilio",
    "inbound_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"
    },
    "source": "user_imported",
    "type": "owned_number",
    "created_at": "2026-11-05T09:00:00Z",
    "inbound_sip_uri": "sip:4k2m9x7q1z.sip.livekit.cloud",
    "created_by": {
      "id": "6f9a3c1e-2b7d-4e58-9a10-3d2c4b5e6f70",
      "email": "jane@example.com",
      "first_name": "Marie",
      "last_name": "Martin"
    },
    "health_status": "healthy",
    "spam_score": 1,
    "health_checked_at": "2026-11-05T09:00:00Z",
    "next_manual_check_at": "2026-11-05T09:00:00Z"
  }
}
```

- `phone_number` ([PhoneNumber](https://www.getrevox.com/docs/api/objects/phone-number.md))

## Errors

- `404` Not found in your organization: `{"error":"Not found"}`
- `429` Too many requests: `{"error":"Too many requests","next_manual_check_at":"2026-11-05T09:00:00Z"}`
- `502` An upstream provider failed: `{"error":"An upstream provider failed"}`
- `503` HTTP 503: `{"error":"HTTP 503"}`
- Every status is explained under Errors in https://www.getrevox.com/docs/api.md#errors.

## Objects on this page

### PhoneNumber

A phone number of your organization: a caller ID for outbound calls and, for an owned number, a line whose inbound calls an assistant can answer.

- `id` (string): Unique ID of the phone number record (UUID): the {id} of PATCH and [`DELETE /phone-numbers/{id}`](https://www.getrevox.com/docs/api/phone-numbers/delete-a-phone-number.md).
- `phone_number` (string): The phone number, in E.164 format. Example: `"+33199001234"`.
- `label` (string | null): Free-text name you gave the number (e.g. 'Paris office'). Null when unset.
- `provider` ("twilio" | "telnyx" | "sip"): Carrier the number is connected through.
  - `"twilio"`: Connected through Twilio.
  - `"telnyx"`: Connected through Telnyx.
  - `"sip"`: Brought over your own SIP trunk.
- `inbound_assistant` ([Assistant](https://www.getrevox.com/docs/api/objects/assistant.md) | null): The assistant that answers inbound calls to this number. Null when inbound calls are not routed to an assistant.
- `source` (enum (3 values)): How the number came in.
  - `"user_imported"`: You connected a number you own.
  - `"revox_provisioned"`: Bought automatically by Revox with your subscription or a top-up. Deleting it also releases it.
  - `"revox_purchased"`: Bought from the dashboard. Deleting it also releases it.
- `type` ("owned_number" | "verified_caller_id"): What the number can be used for.
  - `"owned_number"`: A number Revox can place and receive calls on.
  - `"verified_caller_id"`: An outside number verified with Twilio, only shown as the caller ID of outbound calls. It cannot receive calls.
- `created_at` (string (date-time)): When the number was added (ISO 8601).
- `inbound_sip_uri` (string | null): For a 'sip' number: the SIP URI to configure on your carrier or PBX so inbound calls reach Revox. Null for other providers.
- `created_by` ([OrgMember](https://www.getrevox.com/docs/api/objects/org-member.md) | null): The user who added the number. Null for numbers provisioned by Revox and for numbers added before this was tracked.
- `health_status` ("unknown" | "healthy" | "warning" | "burned"): Spam reputation from the last check. A number is never taken out of service for its reputation.
  - `"unknown"`: Never checked, or the check gave no usable signal. Not a sign the number is clean.
  - `"healthy"`: Spam score under 60, and not flagged by Orange Téléphone.
  - `"warning"`: Spam score from 60 to 70: worth watching, still used like any other number.
  - `"burned"`: Spam score above 70, or flagged as spam by Orange Téléphone: used last in the outbound rotation.
- `spam_score` (number | null): Spam score from 0 to 100 at the last check (HUHU's combined Hiya and Truecaller score), higher meaning more likely flagged as spam. A new number usually starts around 30; above 70 it is considered burned. Null when no check reported one.
- `health_checked_at` (string (date-time) | null): When the reputation was last checked (ISO 8601). Null when never checked.
- `next_manual_check_at` (string (date-time) | null): When [`POST /phone-numbers/{id}/reputation-check`](https://www.getrevox.com/docs/api/phone-numbers/check-a-phone-numbers-spam-reputation-now.md) can next be called for this number (ISO 8601): one manual check per number every 48 hours. Null when it can be called now.

They contain: [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.); [OrgMember](https://www.getrevox.com/docs/api/objects/org-member.md) (A member of the current organization.).