Skip to content
Phone Numbers

Update a phone number

PATCH/phone-numbers/{id}

Rename a phone number, or choose which assistant answers its inbound calls. Only the fields you send are changed.

Path parameters

  • idstringrequired

    ID of the phone number record, as returned by GET /phone-numbers (not the phone number itself).

Request body

  • labelstringnullable

    Free-text name for the number (e.g. 'Paris office'). Null clears it; omit to leave it unchanged.

  • inbound_assistant_idstringnullable

    ID of the assistant that answers inbound calls to this number; it must belong to your organization. Null stops routing inbound calls to an assistant; omit to leave it unchanged.

Response

200
  • phone_numberPhoneNumber
    • 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.

Errors

  • 400Invalid request: a field or parameter failed validation{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }
  • 404Not found in your organization{ "error": string }

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