The PhoneNumber object

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": "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"
}

Returned by

Fields

idstring
Unique ID of the phone number record (UUID): the {id} of PATCH and DELETE /phone-numbers/{id}.
phone_numberstring
The phone number, in E.164 format.
Example "+33199001234"
labelstringnullable
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_assistantAssistantnullable
The assistant that answers inbound calls to this number. Null when inbound calls are not routed to an assistant.
sourceenum (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_atstring (date-time)
When the number was added (ISO 8601).
inbound_sip_uristringnullable
For a 'sip' number: the SIP URI to configure on your carrier or PBX so inbound calls reach Revox. Null for other providers.
created_byOrgMembernullable
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"
Clean everywhere the check looks.
"warning"
Early signs of a spam flag: worth watching, still used.
"burned"
Flagged as spam: used last in the outbound rotation.
spam_scorenumbernullable
Spam score from 0 to 100 at the last check, higher meaning more likely flagged as spam. Null when no check reported one.
health_checked_atstring (date-time)nullable
When the reputation was last checked (ISO 8601). Null when never checked.