List phone numbers
GET/phone_numbers
List phone numbers
Request
Query Parameters
Possible values: >= 1
Default value: 1
The page number to load
Possible values: >= 1
and <= 250
Default value: 20
The size of the page
Filter by phone number tags.
Filter by phone number. Requires at least three digits. Non-numerical characters will result in no values being returned.
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 by connection_id.
Filter contains connection name. Requires at least three characters.
Filter starts with connection name. Requires at least three characters.
Filter ends with connection name. Requires at least three characters.
Filter by connection name.
Possible values: [pay-per-minute
, channel
]
Filter by usage_payment_method.
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 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 numbers via the customer_reference set.
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.
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
data
object[]
Identifies the resource.
Identifies the type of the resource.
The +E.164-formatted phone number associated with this record.
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.
A list of user-assigned tags to help manage the phone number.
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.
The user-assigned name of the connection to be associated with this phone number.
Identifies the connection associated with the phone number.
A customer reference string for customer look ups.
Identifies the messaging profile associated with the phone number.
The name of the messaging profile associated with the phone number.
Identifies the billing group associated with the phone number.
Indicates whether emergency services are enabled for this number.
Identifies the emergency address associated with the phone number.
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.
Indicates whether a CNAM listing is enabled for this number.
Indicates whether caller ID is enabled for this number.
Indicates whether call recording is enabled for this number.
Indicates whether T38 Fax Gateway for inbound calls to this number.
ISO 8601 formatted date indicating when the resource was purchased.
ISO 8601 formatted date indicating when the resource was created.
Possible values: [disabled
]
Default value: disabled
Deprecated field, the only value for this is 'disabled'. All routing for numbers should be configured via connection settings.
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.
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.
meta
object
{
"data": [
{
"id": "1293384261075731499",
"record_type": "phone_number",
"phone_number": "+19705555098",
"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",
"call_forwarding_enabled": true,
"cnam_listing_enabled": true,
"caller_id_name_enabled": true,
"call_recording_enabled": true,
"t38_fax_gateway_enabled": true,
"number_level_routing": "disabled",
"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
}
],
"meta": {
"total_pages": 3,
"total_results": 55,
"page_number": 2,
"page_size": 25
}
}
default: Unexpected error
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
errors
Error[]
source
object
JSON pointer (RFC6901) to the offending entity.
Indicates which query parameter caused the error.
meta
object
URL with additional information on the error.
{
"errors": [
{
"code": "10007",
"title": "Unexpected error",
"detail": "An unexpected error occured.",
"source": {
"pointer": "/base",
"parameter": "string"
},
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10015"
}
}
]
}