List phone numbers

GET

/phone_numbers

Phone Number Configurations

Response Example

200 - Example 1

{
    "data": [
        {
            "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",
            "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"
        }
    ],
    "meta": {
        "page_number": 2,
        "page_size": 25,
        "total_pages": 3,
        "total_results": 55
    }
}

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Query Params

page[number]

integer

optional

The page number to load

>= 1

Default:

page[size]

integer

optional

The size of the page

>= 1<= 250

Default:

filter[tag]

string

optional

Filter by phone number tags.

filter[phone_number]

string

optional

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

filter[status]

enum<string>

optional

Filter by phone number status.

Allowed values:

purchase-pendingpurchase-failedport-pendingactivedeletedport-failedemergency-onlyported-outport-out-pending

Example:

active

filter[country_iso_alpha2]

optional

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

One of

string

array[string]

Example:

filter[connection_id]

string <int64>

optional

Filter by connection_id.

Example:

1521916448077776306

filter[voice.connection_name][contains]

string

optional

Filter contains connection name. Requires at least three characters.

Example:

test

filter[voice.connection_name][starts_with]

string

optional

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

Example:

test

filter[voice.connection_name][ends_with]

string

optional

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

Example:

test

filter[voice.connection_name][eq]

string

optional

Filter by connection name.

Example:

test

filter[voice.usage_payment_method]

enum<string>

optional

Filter by usage_payment_method.

Allowed values:

pay-per-minutechannel

Example:

channel

filter[billing_group_id]

string

optional

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

Example:

62e4bf2e-c278-4282-b524-488d9c9c43b2

filter[emergency_address_id]

string <int64>

optional

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

Example:

9102160989215728032

filter[customer_reference]

string

optional

Filter numbers via the customer_reference set.

filter[number_type][eq]

enum<string>

optional

Filter phone numbers by phone number type.

Allowed values:

localnationaltoll_freemobileshared_cost

filter[source]

enum<string>

optional

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

Allowed values:

portedpurchased

sort

enum<string>

optional

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

Allowed values:

purchased_atphone_numberconnection_nameusage_payment_method

Example:

connection_name

Responses

🟢200OK

application/json

Successful response with a list of phone numbers.

Body

data

array[object (PhoneNumberDetailed) {26}]

optional

billing_group_id

string

optional

Identifies the billing group associated with the phone number.

call_forwarding_enabled

boolean

read-onlyoptional

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.

Default:

true

call_recording_enabled

boolean

read-onlyoptional

Indicates whether call recording is enabled for this number.

caller_id_name_enabled

boolean

read-onlyoptional

Indicates whether caller ID is enabled for this number.

cnam_listing_enabled

boolean

read-onlyoptional

Indicates whether a CNAM listing is enabled for this number.

connection_id

string

optional

Identifies the connection associated with the phone number.

connection_name

string

read-onlyoptional

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

country_iso_alpha2

string

read-onlyoptional

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

Example:

created_at

string

read-onlyoptional

ISO 8601 formatted date indicating when the resource was created.

customer_reference

string

optional

A customer reference string for customer look ups.

Example:

MY REF 001

emergency_address_id

string <int64>

read-onlyoptional

Identifies the emergency address associated with the phone number.

emergency_enabled

boolean

read-onlyoptional

Indicates whether emergency services are enabled for this number.

emergency_status

enum<string>

optional

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.

Allowed values:

activedeprovisioningdisabledprovisioningprovisioning-failed

external_pin

string

optional

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.

string <int64>

optional

Uniquely identifies the resource.

Example:

1293384261075731499

inbound_call_screening

enum<string>

optional

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.

Allowed values:

disabledreject_callsflag_calls

Default:

disabled

messaging_profile_id

string

optional

Identifies the messaging profile associated with the phone number.

messaging_profile_name

string

optional

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

Example:

regional-customers

phone_number

string

read-onlyoptional

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

phone_number_type

enum<string>

read-onlyoptional

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.

Allowed values:

localtoll_freemobilenationalshared_costlandlinetollfreeshortcodelongcode

purchased_at

string

read-onlyoptional

ISO 8601 formatted date indicating when the resource was purchased.

record_type

string

read-onlyoptional

Identifies the type of the resource.

Example:

phone_number

source_type

enum<string> | enum<null>

read-onlyoptional

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

Allowed values:

number_orderport_request

status

enum<string>

read-onlyoptional

The phone number's current status.

Allowed values:

purchase-pendingpurchase-failedport-pendingport-failedactivedeletedemergency-onlyported-outport-out-pendingrequirement-info-pendingrequirement-info-under-reviewrequirement-info-exceptionprovision-pending

t38_fax_gateway_enabled

boolean

read-onlyoptional

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