Number Search - Finding The Perfect Phone Number' 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)
You can search for numbers by region, number, prefix, rate center, type, or enabled features.
The example below shows a generic number search for two phone numbers.
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[limit]=2"
Note: Don't forget to update
YOUR_API_KEY
here.
Sample Number Search Response' 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)
{
"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": "+17732490564",
"record_type": "available_phone_number",
"region_information": [
{
"region_name": "US",
"region_type": "country_code"
},
{
"region_name": "IL",
"region_type": "state"
},
{
"region_name": "CHICAGO ZONE 11",
"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": "+17732490565",
"record_type": "available_phone_number",
"region_information": [
{
"region_name": "US",
"region_type": "country_code"
},
{
"region_name": "IL",
"region_type": "state"
},
{
"region_name": "CHICAGO ZONE 11",
"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 search requests are detailed below.
Search by 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.
The national_destination_code
parameter can be set to search by NPA.
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"
Searching for NPA and NXX:
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[phone_number][starts_with]=359&filter[limit]=2"
Search by City
Specifying a country and city.
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[limit]=2"
Search by Region
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[administrative_area]=IL&filter[limit]=2"
Search by Toll-Free Prefix
"800", "888", etc…
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[number_type]=toll-free&filter[national_destination_code]=877&filter[limit]=2"