GET /list-phone-numbers — retell-sdk

List all phone numbers

get/list-phone-numbers

Response

Successfully retrieved all phone numbers.

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

Changes

Changed in 8 of the 28 revisions of this API.4621

May 28, 202640402ca870b94See the full diff
- ○
  the //// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the //// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the //// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the //// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
May 8, 20267dd16ddf69d84See the full diff
- ○
  the //// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the //// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the //// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the //// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
May 7, 2026f1a0d7c1e36c4See the full diff
- ▲
  response property items/inbound_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property items/inbound_sms_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property items/outbound_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property items/outbound_sms_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
Apr 28, 20261b4a9d84942a1See the full diff
- ○
  endpoint deprecated
  endpoint-deprecated
Apr 20, 20268ee53928bf314See the full diff
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
Feb 23, 2026bcff6899fa2a4See the full diff
- ○
  response property items/inbound_agent_id deprecated
  response-property-deprecated
- ○
  response property items/inbound_agent_version deprecated
  response-property-deprecated
- ○
  response property items/outbound_agent_id deprecated
  response-property-deprecated
- ○
  response property items/outbound_agent_version deprecated
  response-property-deprecated
Feb 6, 2026dfad228ab4a46See the full diff
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jan 23, 2026427e77039f3922See the full diff
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added

Full history