Sign in

v28

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-05-2887246443.7 KB

Retrieve details of a specific phone number

get/get-phone-number/{phone_number}

Path parameters

phone_numberstring required
Example:+14157774444

E.164 format of the number (+country code, then number with no space, no special characters), used as the unique identifier for phone number APIs.

Response

Successfully retrieved a phone number.

phone_numberstring required

E.164 format of the number (+country code, then number with no space, no special characters), used as the unique identifier for phone number APIs.

phone_number_type'retell-twilio' | 'retell-telnyx' | 'custom' required

Type of the phone number.

phone_number_prettystring

Pretty printed phone number, provided for your reference.

allowed_inbound_country_liststring[] nullable

List of ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. If not set or empty, calls from all countries are allowed.

allowed_outbound_country_liststring[] nullable

List of ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. If not set or empty, calls to all countries are allowed.

area_codeinteger

Area code of the number to obtain. Format is a 3 digit integer. Currently only supports US area code.

nicknamestring nullable

Nickname of the number. This is for your reference only.

inbound_webhook_urlstring nullable

If set, will send a webhook for inbound calls, where you can to override agent id, set dynamic variables and other fields specific to that call.

inbound_sms_webhook_urlstring nullable

If set, will send a webhook for inbound SMS, where you can override agent id, set dynamic variables and other fields specific to that chat.

last_modification_timestampinteger required

Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

fallback_numberstring nullable

Enterprise only. Phone number to transfer inbound calls to when organization is in outage mode or when an inbound call cannot get a concurrency slot before the fallback timeout. Can be either a Retell phone number or an external number. Cannot be the same as this phone number, and cannot be a number that already has its own fallback configured (prevents nested forwarding).

Example response

{
  "phone_number": "+14157774444",
  "phone_number_type": "retell-twilio",
  "phone_number_pretty": "+1 (415) 777-4444",
  "allowed_inbound_country_list": [
    "US",
    "CA",
    "GB"
  ],
  "allowed_outbound_country_list": [
    "US",
    "CA"
  ],
  "area_code": 415,
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "inbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "outbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "nickname": "Frontdesk Number",
  "inbound_webhook_url": "https://example.com/inbound-webhook",
  "inbound_sms_webhook_url": "https://example.com/inbound-sms-webhook",
  "last_modification_timestamp": 1703413636133,
  "sip_outbound_trunk_config": {
    "termination_uri": "someuri.pstn.twilio.com",
    "auth_username": "username",
    "transport": "TCP"
  },
  "fallback_number": "+14155551234"
}