Sign in
Phone Number Configurations

List phone numbers

Returns phone numbers associated with the account. Results support pagination, sorting, and filters for number attributes, status, source, connections, billing groups, emergency addresses, tags, and customer references.

get/phone_numbers

Query parameters

sizeinteger

The size of the page

numberinteger

The page number to load

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.

tagstring

Filter by phone number tags.

without_tags'true' | 'false'

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

phone_numberstring

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

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

Filter by phone number status.

connection_idstring

Filter by connection_id.

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

Filter by usage_payment_method.

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

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

customer_referencestring

Filter numbers via the customer_reference set.

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.

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]

{
  "status": "active",
  "country_iso_alpha2": "US",
  "connection_id": "1521916448077776306",
  "voice.connection_name": {
    "contains": "test",
    "starts_with": "test",
    "ends_with": "test",
    "eq": "test"
  },
  "voice.usage_payment_method": "channel",
  "billing_group_id": "62e4bf2e-c278-4282-b524-488d9c9c43b2",
  "emergency_address_id": "9102160989215728032"
}
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": [
    {
      "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",
      "deletion_lock_enabled": false,
      "activated_at": "2019-10-23T18:10:00.000Z"
    }
  ],
  "meta": {
    "total_pages": 3,
    "total_results": 55,
    "page_number": 2,
    "page_size": 25
  },
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

Changes

Changed in 6 of the 99 revisions of this API.251127

  • 96654ba6a1b11See the full diff
    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • a6a61a29ecdd5510See the full diff
    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ●

      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

    • ●

      removed the optional property /// from the response with the status

      response-optional-property-removed

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    This revision also has 34 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 1571b0380bd7155See the full diff
    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the response property // became optional for the status

      response-property-became-optional

    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    • ○

      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 64 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 8f5f4e5379945510See the full diff
    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ●

      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

    • ●

      removed the optional property /// from the response with the status

      response-optional-property-removed

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    • ○

      the response property // became required for the status

      response-property-became-required

    This revision also has 41 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • b1f7c46528b51See the full diff
    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • 224ed0d8a5c31See the full diff
    • ●

      removed the optional property // from the response with the status

      response-optional-property-removed

    This revision also has 111 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 99 revisions, 1 has no diff computed.