---
title: "List Phone Numbers Page"
method: GET
path: "/v1/convai/v2/phone-numbers"
tags: ["Agents Platform"]
---

# List Phone Numbers Page

`GET /v1/convai/v2/phone-numbers`

Retrieve a page of Phone Numbers

## Query parameters

- `page_size` integer — Number of phone numbers per page
- `search` string, nullable — Filter by phone number ID, label, or phone number. A phone number ID must match exactly; label and phone number matching is a case-insensitive substring.
- `label` string, nullable — Filter by label. Matching is a case-insensitive substring.
- `phone_number` string, nullable — Filter by phone number
- `provider` 'twilio' | 'sip_trunk' | 'exotel'
- `supports_outbound` boolean, nullable — Filter by whether the phone number can place outbound calls
- `agent_id` string, nullable — Filter by assigned agent ID
- `branch_id` string, nullable — Filter by assigned branch ID
- `sort_by` 'label' | 'phone_number'
- `sort_direction` 'asc' | 'desc'
- `cursor` string, nullable — Used for fetching next page. Cursor is returned in the response.

## Headers

- `xi-api-key` string, nullable — Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Response `200`

Successful Response

- GetPhoneNumbersPageResponseModel
  - `phone_numbers` union[], required — The phone numbers on this page
    - union
      - GetPhoneNumberTwilioResponseModel
        - `phone_number` string, required — Phone number
        - `label` string, required — Label for the phone number
        - `supports_inbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports inbound calls
        - `supports_outbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports outbound calls
        - `phone_number_id` string, required — The ID of the phone number
        - `assigned_agent` PhoneNumberAgentInfo
          - `agent_id` string, required — The ID of the agent
          - `agent_name` string, required — The name of the agent
          - `environment` string, nullable — Environment to use for resolving environment variables on calls to this number.
          - `branch_id` string, nullable — Agent branch to use for calls to this number.
        - `provider` 'twilio' — Phone provider
      - GetPhoneNumberExotelResponseModel
        - `phone_number` string, required — Phone number
        - `label` string, required — Label for the phone number
        - `supports_inbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports inbound calls
        - `supports_outbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports outbound calls
        - `phone_number_id` string, required — The ID of the phone number
        - `assigned_agent` PhoneNumberAgentInfo
          - `agent_id` string, required — The ID of the agent
          - `agent_name` string, required — The name of the agent
          - `environment` string, nullable — Environment to use for resolving environment variables on calls to this number.
          - `branch_id` string, nullable — Agent branch to use for calls to this number.
        - `provider` 'exotel' — Phone provider
      - GetPhoneNumberSIPTrunkResponseModel
        - `phone_number` string, required — Phone number
        - `label` string, required — Label for the phone number
        - `supports_inbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports inbound calls
        - `supports_outbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports outbound calls
        - `phone_number_id` string, required — The ID of the phone number
        - `assigned_agent` PhoneNumberAgentInfo
          - `agent_id` string, required — The ID of the agent
          - `agent_name` string, required — The name of the agent
          - `environment` string, nullable — Environment to use for resolving environment variables on calls to this number.
          - `branch_id` string, nullable — Agent branch to use for calls to this number.
        - `provider` 'sip_trunk' — Phone provider
        - `provider_config` GetPhoneNumberOutboundSIPTrunkConfigResponseModel — SIP Trunk configuration details for a phone number
          - `address` string, required — Hostname or IP the SIP INVITE is sent to
          - `transport` 'auto' | 'udp' | 'tcp' | 'tls', required
          - `media_encryption` 'disabled' | 'allowed' | 'required', required
          - `headers` object — SIP headers for INVITE request
          - `attributes_to_headers` object — Map of dynamic variable name to header name for attributes_to_headers
          - `has_auth_credentials` boolean, required — Whether authentication credentials are configured
          - `username` string, nullable — SIP trunk username (if available)
          - `has_outbound_trunk` boolean — Whether a LiveKit SIP outbound trunk is configured
          - `enabled_codecs` MediaCodec[] — Media codecs that are offered in the SDP for outbound calls. If empty, all supported codecs are offered.
        - `outbound_trunk` GetPhoneNumberOutboundSIPTrunkConfigResponseModel — SIP Trunk configuration details for a phone number
          - `address` string, required — Hostname or IP the SIP INVITE is sent to
          - `transport` 'auto' | 'udp' | 'tcp' | 'tls', required
          - `media_encryption` 'disabled' | 'allowed' | 'required', required
          - `headers` object — SIP headers for INVITE request
          - `attributes_to_headers` object — Map of dynamic variable name to header name for attributes_to_headers
          - `has_auth_credentials` boolean, required — Whether authentication credentials are configured
          - `username` string, nullable — SIP trunk username (if available)
          - `has_outbound_trunk` boolean — Whether a LiveKit SIP outbound trunk is configured
          - `enabled_codecs` MediaCodec[] — Media codecs that are offered in the SDP for outbound calls. If empty, all supported codecs are offered.
        - `inbound_trunk` GetPhoneNumberInboundSIPTrunkConfigResponseModel
          - `allowed_addresses` string[], required — List of IP addresses that are allowed to use the trunk. Each item in the list can be an individual IP address or a Classless Inter-Domain Routing notation representing a CIDR block.
          - `allowed_numbers` string[], nullable, required — List of phone numbers that are allowed to use the trunk.
          - `media_encryption` 'disabled' | 'allowed' | 'required', required
          - `has_auth_credentials` boolean, required — Whether authentication credentials are configured
          - `username` string, nullable — SIP trunk username (if available)
          - `remote_domains` string[], nullable — Domains of remote SIP servers used to validate TLS certificates.
          - `attributes_to_headers` object — Map of dynamic variable name to header name for attributes_to_headers
        - `livekit_stack` 'standard' | 'static', required
        - `store_sip_messages` boolean — Whether to store SIP messages for this phone number.
  - `next_cursor` string, nullable — Pass this value as `cursor` to fetch the next page. Null when there are no more results.
  - `has_more` boolean — Whether there are more results available

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-19** `e1bb68b2a601` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/changes/v1/convai/v2/phone-numbers/get.md)

---

[API](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/revisions/4a6716242c9e?raw)