---
title: "POST /v2/list-phone-numbers"
method: POST
path: "/v2/list-phone-numbers"
---

# POST /v2/list-phone-numbers

`POST /v2/list-phone-numbers`

## Request

- Base URL: `https://api.retellai.com`
- URL: `https://api.retellai.com/v2/list-phone-numbers`
- Auth: HTTP bearer

List phone numbers with filters and pagination.

## Query parameters

- `limit` integer
- `sort_order` 'ascending' | 'descending'
- `pagination_key` string

## Request body

- object
  - `filter_criteria` PhoneNumberListFilter: Filters for listing phone numbers. All provided filters are connected with AND.
    - `query` string: Substring match against the phone number, pretty phone number, or nickname. The nickname match ignores case.
    - `spam_status` object
      - `type` 'enum', required
      - `op` 'in', required: in: value is one of the listed values
      - `value` string[], required
    - `sms` object: Matches numbers that have a custom SMS configuration or an approved A2P application.
      - `type` 'boolean', required
      - `op` 'eq', required
      - `value` true, required
    - `verified_number` object: Matches numbers that have an active phone verification.
      - `type` 'boolean', required
      - `op` 'eq', required
      - `value` true, required
    - `branded_call` object: Matches numbers that have an active branded call registration.
      - `type` 'boolean', required
      - `op` 'eq', required
      - `value` true, required
    - `phone_number_type` object
      - `type` 'enum', required
      - `op` 'in', required: in: value is one of the listed values
      - `value` string[], required
    - `inbound_agents` object[]: Matches numbers with any listed agent among their inbound agents. For an agent with `version`, a number matches when it is bound to a listed version or to a tag in `inbound_agent_tags`.
      - `agent_id` string, required: The agent ID to filter on.
      - `version` number[]: Specific versions to filter on. If omitted or empty, all versions are included.
    - `inbound_agent_tags` object: Agent version tags, such as `production`. Without `inbound_agents`, matches numbers whose inbound agent is bound through one of these tags.
      - `type` 'enum', required
      - `op` 'in', required: in: value is one of the listed values
      - `value` string[], required
    - `outbound_agents` object[]: Matches numbers with any listed agent among their outbound agents. For an agent with `version`, a number matches when it is bound to a listed version or to a tag in `outbound_agent_tags`.
      - `agent_id` string, required: The agent ID to filter on.
      - `version` number[]: Specific versions to filter on. If omitted or empty, all versions are included.
    - `outbound_agent_tags` object: Agent version tags, such as `production`. Without `outbound_agents`, matches numbers whose outbound agent is bound through one of these tags.
      - `type` 'enum', required
      - `op` 'in', required: in: value is one of the listed values
      - `value` string[], required

## Response `200`

Successfully retrieved phone numbers.

- object
  - `pagination_key` string: Pagination key for the next page.
  - `has_more` boolean, required: Whether more results are available.
  - `items` PhoneNumberResponse[], required
    - `phone_number` string, 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' | 'retell-bandwidth' | 'custom', required: Type of the phone number.
    - `phone_number_pretty` string: Pretty printed phone number, provided for your reference.
    - `allowed_inbound_country_list` string[], 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_list` string[], 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_code` integer: Area code of the number to obtain. Format is a 3 digit integer. Currently only supports US area code.
    - `custom_sms_enabled` boolean, required: Whether the number has a custom SMS configuration.
    - `sms_enabled` boolean: Whether the number can send SMS, through a custom SMS configuration or an approved A2P application. Returned only by `GET` and `POST` `/v2/list-phone-numbers`.
    - `spam_status` 'clean' | 'spam': Latest spam test result for this number. Absent until the first vendor result arrives.
    - `spam_check_enabled` boolean: Whether this number is enrolled in daily spam testing.
    - `inbound_agents` AgentWeight[], nullable: Inbound agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each inbound call, with probability proportional to the weight. Total weights must add up to 1.
      - `agent_id` string, required
      - `agent_version` union: Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
        - string
        - integer
      - `weight` number, required: The weight of the agent. When used in a list of agents, the total weights must add up to 1.
    - `outbound_agents` AgentWeight[], nullable: Outbound agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each outbound call, with probability proportional to the weight. Total weights must add up to 1.
      - `agent_id` string, required
      - `agent_version` union: Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
        - string
        - integer
      - `weight` number, required: The weight of the agent. When used in a list of agents, the total weights must add up to 1.
    - `inbound_sms_agents` AgentWeight[], nullable: Inbound SMS agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each inbound SMS, with probability proportional to the weight. Total weights must add up to 1.
      - `agent_id` string, required
      - `agent_version` union: Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
        - string
        - integer
      - `weight` number, required: The weight of the agent. When used in a list of agents, the total weights must add up to 1.
    - `outbound_sms_agents` AgentWeight[], nullable: Outbound SMS agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each outbound SMS, with probability proportional to the weight. Total weights must add up to 1.
      - `agent_id` string, required
      - `agent_version` union: Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
        - string
        - integer
      - `weight` number, required: The weight of the agent. When used in a list of agents, the total weights must add up to 1.
    - `nickname` string, nullable: Nickname of the number. This is for your reference only.
    - `inbound_webhook_url` string, nullable: If set, Retell will send a webhook for inbound calls, where you can override the agent ID, set dynamic variables, reject the call, and configure other fields specific to that call. Includes call_inbound.call_id for deduplication across HTTP retries. Early setup failures may not create a call history record.
    - `inbound_sms_webhook_url` string, nullable: If set, Retell will send a webhook for inbound SMS, where you can override the agent ID, set dynamic variables, reject the SMS, and configure other fields specific to that chat. Includes chat_inbound.chat_id for deduplication across HTTP retries. Early setup failures may not create a chat history record.
    - `last_modification_timestamp` integer, required: Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.
    - `sip_outbound_trunk_config` object, nullable
      - `termination_uri` string, nullable: The termination URI for the SIP trunk for the phone number.
      - `auth_username` string, nullable: The username used for authenticating the SIP trunk for the phone number.
      - `transport` string, nullable: Outbound transport protocol for the SIP trunk for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
      - `codecs` string[]: SIP codec preferences for custom phone numbers only, used for inbound and outbound gateway calls. Retell-managed Twilio and Telnyx phone numbers do not support this setting. An empty list uses the gateway's default codecs. Codec names are extensible and are not limited to the examples.
    - `fallback_number` string, nullable: When inbound call concurrency is reached and a slot does not free up after extended ringing, the call will fall back to this number. 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).
    - `inbound_fallback_enabled` boolean: Whether inbound fallback is enabled for this phone number. When enabled, inbound calls are transferred to the fallback number.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-11-13** `31dfa851d982`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/retellai/apis/retell-sdk/changes/v2/list-phone-numbers/post.md)

---

[API](https://skmtc.dev/retellai/apis/retell-sdk.md) - [All operations](https://skmtc.dev/retellai/apis/retell-sdk/llms.txt) - [OpenAPI document](https://skmtc.dev/retellai/apis/retell-sdk/revisions/31dfa851d982?raw)