Skip to main content

List phone numbers

GET 
/phone_numbers

List phone numbers

Request ​

Query Parameters

    page[number] integer

    Possible values: >= 1

    Default value: 1

    The page number to load

    page[size] integer

    Possible values: >= 1 and <= 250

    Default value: 20

    The size of the page

    filter[tag] string

    Filter by phone number tags.

    filter[phone_number] string

    Filter by phone number. Requires at least three digits. Non-numerical characters will result in no values being returned.

    filter[status] string

    Possible values: [purchase-pending, purchase-failed, port-pending, active, deleted, port-failed, emergency-only, ported-out, port-out-pending]

    Filter by phone number status.

    filter[country_iso_alpha2] any

    Filter by phone number country ISO alpha-2 code. Can be a single value or an array of values.

    filter[connection_id] int64

    Filter by connection_id.

    filter[voice.connection_name][contains] string

    Filter contains connection name. Requires at least three characters.

    filter[voice.connection_name][starts_with] string

    Filter starts with connection name. Requires at least three characters.

    filter[voice.connection_name][ends_with] string

    Filter ends with connection name. Requires at least three characters.

    filter[voice.connection_name][eq] string

    Filter by connection name.

    filter[voice.usage_payment_method] string

    Possible values: [pay-per-minute, channel]

    Filter by usage_payment_method.

    filter[billing_group_id] string

    Filter by the billing_group_id associated with phone numbers. To filter to only phone numbers that have no billing group associated them, set the value of this filter to the string 'null'.

    filter[emergency_address_id] int64

    Filter by the emergency_address_id associated with phone numbers. To filter only phone numbers that have no emergency address associated with them, set the value of this filter to the string 'null'.

    filter[customer_reference] string

    Filter numbers via the customer_reference set.

    filter[number_type][eq] string

    Possible values: [local, national, toll_free, mobile, shared_cost]

    Filter phone numbers by phone number type.

    filter[source] string

    Possible values: [ported, purchased]

    Filter phone numbers by their source. Use 'ported' for numbers ported from other carriers, or 'purchased' for numbers bought directly from Telnyx.

    sort string

    Possible values: [purchased_at, phone_number, connection_name, usage_payment_method]

    Specifies the sort order for results. If not given, results are sorted by created_at in descending order.

Responses ​

200: Successful response with a list of phone numbers.

Schema

    data

    object[]

  • Array [

    • id int64

    Identifies the resource.

    record_type string

    Identifies the type of the resource.

    phone_number string

    The +E.164-formatted phone number associated with this record.

    country_iso_alpha2 string

    The ISO 3166-1 alpha-2 country code of the phone number.

    status string

    Possible values: [purchase-pending, purchase-failed, port-pending, port-failed, active, deleted, emergency-only, ported-out, port-out-pending, requirement-info-pending, requirement-info-under-review, requirement-info-exception, provision-pending]

    The phone number's current status.

    tags string[]

    A list of user-assigned tags to help manage the phone number.

    external_pin string

    If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, Telnyx will attempt to verify that you provided the correct external PIN to the winning carrier. Note that not all carriers cooperate with this security mechanism.

    connection_name string

    The user-assigned name of the connection to be associated with this phone number.

    connection_id string

    Identifies the connection associated with the phone number.

    customer_reference string

    A customer reference string for customer look ups.

    messaging_profile_id string

    Identifies the messaging profile associated with the phone number.

    messaging_profile_name string

    The name of the messaging profile associated with the phone number.

    billing_group_id string

    Identifies the billing group associated with the phone number.

    emergency_enabled boolean

    Indicates whether emergency services are enabled for this number.

    emergency_address_id int64

    Identifies the emergency address associated with the phone number.

    emergency_status string

    Possible values: [active, deprovisioning, disabled, provisioning, provisioning-failed]

    Indicates the status of the provisioning of emergency services for the phone number. This field contains information about activity that may be ongoing for a number where it either is being provisioned or deprovisioned but is not yet enabled/disabled.

    call_forwarding_enabled boolean

    Default value: true

    Indicates if call forwarding will be enabled for this number if forwards_to and forwarding_type are filled in. Defaults to true for backwards compatibility with APIV1 use of numbers endpoints.

    cnam_listing_enabled boolean

    Indicates whether a CNAM listing is enabled for this number.

    caller_id_name_enabled boolean

    Indicates whether caller ID is enabled for this number.

    call_recording_enabled boolean

    Indicates whether call recording is enabled for this number.

    t38_fax_gateway_enabled boolean

    Indicates whether T38 Fax Gateway for inbound calls to this number.

    purchased_at string

    ISO 8601 formatted date indicating when the resource was purchased.

    created_at string

    ISO 8601 formatted date indicating when the resource was created.

    phone_number_type string

    Possible values: [local, toll_free, mobile, national, shared_cost, landline, tollfree, shortcode, longcode]

    The phone number's type. Note: For numbers purchased prior to July 2023 or when fetching a number's details immediately after a purchase completes, the legacy values tollfree, shortcode or longcode may be returned instead.

    inbound_call_screening string

    Possible values: [disabled, reject_calls, flag_calls]

    Default value: disabled

    The inbound_call_screening setting is a phone number configuration option variable that allows users to configure their settings to block or flag fraudulent calls. It can be set to disabled, reject_calls, or flag_calls. This feature has an additional per-number monthly cost associated with it.

    source_type stringnullable

    Possible values: [number_order, port_request]

    Indicates if the phone number was purchased or ported in. For some numbers this information may not be available.

  • ]

    • meta

    object

    total_pages integer
    total_results integer
    page_number integer
    page_size integer

default: Unexpected error

Schema

    errors

    Error[]

  • Array [

    • code integerrequired
    title stringrequired
    detail string

    source

    object

    pointer json-pointer

    JSON pointer (RFC6901) to the offending entity.

    parameter string

    Indicates which query parameter caused the error.

    meta

    object

    url string

    URL with additional information on the error.

  • ]

Request samples

curl -L 'https://api.telnyx.com/v2/phone_numbers' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Response samples

{
  "data": [
    {
      "id": "1293384261075731499",
      "record_type": "phone_number",
      "phone_number": "+19705555098",
      "country_iso_alpha2": "US",
      "status": "active",
      "tags": [
        "tag_1",
        "tag_2"
      ],
      "external_pin": "1234",
      "connection_id": "1293384261075731499",
      "connection_name": "connection-name",
      "customer_reference": "customer-reference",
      "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600000000",
      "messaging_profile_name": "regional-customers",
      "billing_group_id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
      "emergency_enabled": true,
      "emergency_address_id": "1315261609962112019",
      "emergency_status": "active",
      "call_forwarding_enabled": true,
      "cnam_listing_enabled": true,
      "caller_id_name_enabled": true,
      "call_recording_enabled": true,
      "t38_fax_gateway_enabled": true,
      "phone_number_type": "local",
      "inbound_call_screening": "disabled",
      "purchased_at": "2019-10-23T18:10:00.000Z",
      "created_at": "2019-10-23T18:10:00.000Z",
      "updated_at": "2019-10-24T18:10:00.000Z",
      "hd_voice_enabled": true,
      "source_type": "number_order"
    }
  ],
  "meta": {
    "total_pages": 3,
    "total_results": 55,
    "page_number": 2,
    "page_size": 25
  }
}