Sign in

v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB
Phone Number Configurations

List phone numbers

get/phone_numbers

Query parameters

numberinteger

The page number to load

sizeinteger

The size of the page

Consolidated page parameter (deepObject style). Originally: page[size], page[number]

sort'purchased_at' | 'phone_number' | 'connection_name' | 'usage_payment_method'
Example:connection_name

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

billing_group_idstring

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'.

connection_idstring

Filter by connection_id.

customer_referencestring

Filter numbers via the customer_reference set.

emergency_address_idstring

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'.

phone_numberstring

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

source'ported' | 'purchased'

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

status'purchase-pending' | 'purchase-failed' | 'port-pending' | 'active' | 'deleted' | 'port-failed' | 'emergency-only' | 'ported-out' | 'port-out-pending'

Filter by phone number status.

tagstring

Filter by phone number tags.

voice.usage_payment_method'pay-per-minute' | 'channel'

Filter by usage_payment_method.

without_tags'true' | 'false'

When set to 'true', filters for phone numbers that do not have any tags applied. All other values are ignored.

Consolidated filter parameter (deepObject style). Originally: filter[tag], filter[phone_number], filter[status], filter[country_iso_alpha2], filter[connection_id], filter[voice.connection_name], filter[voice.usage_payment_method], filter[billing_group_id], filter[emergency_address_id], filter[customer_reference], filter[number_type], filter[source]

{
  "billing_group_id": "62e4bf2e-c278-4282-b524-488d9c9c43b2",
  "connection_id": "1521916448077776306",
  "country_iso_alpha2": "US",
  "emergency_address_id": "9102160989215728032",
  "status": "active",
  "voice.connection_name": {
    "contains": "test",
    "ends_with": "test",
    "eq": "test",
    "starts_with": "test"
  },
  "voice.usage_payment_method": "channel"
}
handle_messaging_profile_error'true' | 'false'
Example:false

Although it is an infrequent occurrence, due to the highly distributed nature of the Telnyx platform, it is possible that there will be an issue when loading in Messaging Profile information. As such, when this parameter is set to true and an error in fetching this information occurs, messaging profile related fields will be omitted in the response and an error message will be included instead of returning a 503 error.

Response

Successful response with a list of phone numbers.

Example response

{
  "data": [
    {
      "activated_at": "2019-10-23T18:10:00.000Z",
      "billing_group_id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
      "call_forwarding_enabled": true,
      "call_recording_enabled": true,
      "caller_id_name_enabled": true,
      "cnam_listing_enabled": true,
      "connection_id": "1293384261075731499",
      "connection_name": "connection-name",
      "country_iso_alpha2": "US",
      "created_at": "2019-10-23T18:10:00.000Z",
      "customer_reference": "customer-reference",
      "deletion_lock_enabled": false,
      "emergency_address_id": "1315261609962112019",
      "emergency_enabled": true,
      "emergency_status": "active",
      "external_pin": "1234",
      "hd_voice_enabled": true,
      "id": "1293384261075731499",
      "inbound_call_screening": "disabled",
      "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600000000",
      "messaging_profile_name": "regional-customers",
      "phone_number": "+19705555098",
      "phone_number_type": "local",
      "purchased_at": "2019-10-23T18:10:00.000Z",
      "record_type": "phone_number",
      "source_type": "number_order",
      "status": "active",
      "t38_fax_gateway_enabled": true,
      "tags": [
        "tag_1",
        "tag_2"
      ],
      "updated_at": "2019-10-24T18:10:00.000Z"
    }
  ],
  "errors": [
    {
      "code": "10007",
      "detail": "An unexpected error occured.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      },
      "source": {
        "pointer": "/base"
      },
      "title": "Unexpected error"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}