Advanced Number Search' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
This guide will cover everything you need to know about performing advanced number searches.
When performing your search, *
matches any character; TELE
matches "8353"; &&
matches "11", "22", etc. You can also use consecutive
to search for numbers in sequence e.g. xxx-xxx-1234, xxx-xxx-1235.
How to perform an advanced number search' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
To show all available filters, see the full documentation here
Check out the Development Environment Setup guide to acquire your API Key and set up a Telnyx SDK if applicable.
curl -X GET \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[locality][]=Chicago&filter[administrative_area][]=IL&filter[features][]=sms&filter[limit][]=2"
Note: Sample results can vary depending on the available numbers at a given moment.
{
"data": [
{
"best_effort": false,
"cost_information": {
"currency": "USD",
"monthly_cost": "1.00000",
"upfront_cost": "1.00000"
},
"features": [
{
"name": "fax"
},
{
"name": "voice"
},
{
"name": "sms"
}
],
"phone_number": "+18728880024",
"record_type": "available_phone_number",
"region_information": [
{
"region_name": "US",
"region_type": "country_code"
},
{
"region_name": "IL",
"region_type": "state"
},
{
"region_name": "CHICAGO ZONE 02",
"region_type": "rate_center"
}
],
"reservable": false,
"vanity_format": null
},
{
"best_effort": false,
"cost_information": {
"currency": "USD",
"monthly_cost": "1.00000",
"upfront_cost": "1.00000"
},
"features": [
{
"name": "fax"
},
{
"name": "voice"
},
{
"name": "sms"
}
],
"phone_number": "+18728880026",
"record_type": "available_phone_number",
"region_information": [
{
"region_name": "US",
"region_type": "country_code"
},
{
"region_name": "IL",
"region_type": "state"
},
{
"region_name": "CHICAGO ZONE 02",
"region_type": "rate_center"
}
],
"reservable": false,
"vanity_format": null
}
],
"metadata": {
"best_effort_results": 0,
"total_results": 2
},
"url": "/v2/available_phone_numbers"
}
Some example payloads for advanced search requests are detailed below.
Advanced NPA/NXX
"NPA" stands for Number Plan Area, commonly called Area Code. "NXX" refers to the three digits of a phone number immediately following the area code, also called the "exchange" or the Central Switching Office Designation. Each DID is typically made up of NPA-NXX-FDN. The FDN (Fixed Dialer Number) refers to the 4 digits that follow the NXX.
Note: *The
phone_number
filter can only be used once per search. For example, if you want to search for a number that starts with "12" and ends with "AB" you could use astarts_with
search passing in the following value "12**AB"
The below search is looking for any digits for the first 3 digits (the NPA), followed by a 2, and then a repeated digit.
curl -X GET \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[national_destination_code][]=877&filter[phone_number][starts_with]=***2&&&filter[limit][]=2"
Advanced Region
Search for numbers in a region with additional filters. The FDN (Fixed Dialer Number) refers to the 4 digits that follow the NXX. Each DID is typically made up of NPA-NXX-FDN. FDN can be searched for using the ends_with
parameter.
curl -X GET \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[locality][]=Chicago&filter[phone_number][ends_with]=ABC*&filter[limit][]=2"
Advanced Rate Center
curl -X GET \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[rate_center][]=CHICAGO HEIGHTS&filter[administrative_area][]=IL&filter[limit][]=2"
Limiting Search Results
curl -X GET \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[national_destination_code][]=312&filter[limit][]=2"
Feature Search
Limits search results to having certain features. For example, you can choose to search for only SMS enabled numbers by limiting the features
parameter to just "sms".
curl -X GET \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[features][]=sms&filter[limit][]=2"
You could also search for number with SMS and MMS capabilities.
curl -X GET \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[features][]=sms&filter[features][]=mms&filter[limit][]=2"
Possible features: "sms", "mms", "voice", "fax"
Disabling Best Effort Search
By default, best_effort
is enabled on all searches. To omit best effort results, set the best_effort
key to false in your search request:
curl -X GET \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[national_destination_code][]=312&filter[best_effort][]=false&filter[limit][]=2"