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.
To show all available filters, see the full documentation here
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "x-api-token: YOUR_API_TOKEN" \
--data '{"search_descriptor":{"consecutive":4,"city":"Chicago","state":"IL","has_any_features":["sms","voice"]},"search_type":4,"limit":1}' \
"https://api.telnyx.com/origination/number_searches"
Note: Sample result can vary depending on the available numbers at a given moment.
{
"id": "123-45678-5678",
"result": [
{
"number_vanity": null,
"upfront_cost": "1.00000",
"vanity_string": null,
"monthly_recurring_cost": "1.00000",
"verification_requirements": [],
"regional_data": {
"rate_center": "CHICAGO HEIGHTS",
"state": "IL",
"country_iso": "US"
},
"features": [
{
"name": "fax"
},
{
"name": "voice"
},
{
"name": "sms"
}
],
"number_e164": "+15558520334",
"reservable": false,
"currency": "USD",
"best_effort": false
}
],
"inexplicit_result": [],
"search_descriptor": {
"has_all_features": [],
"rc_name": null,
"province": "IL",
"consecutive": 4,
"national_destination_codes": null,
"subscriber_number": null,
"vanity_string": null,
"postal_code": null,
"prefix": null,
"trailing_digits": null,
"has_any_features": [
"sms",
"voice"
],
"user_source": "api",
"national_destination_code": null,
"city": "Chicago",
"placement": null,
"country_iso": "US",
"reservable": false,
"best_effort": true
},
"status": 2,
"limit": 1
}
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
{
"search_descriptor": {
"npa": "8*",
"nxx": "4&&",
"fdn": "ABC*",
"consecutive": 4
}
}
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
{
"search_descriptor": {
"fdn": "ABC*",
"consecutive": 4,
"city": "Chicago",
"state": "IL"
}
}
Advanced Rate Center
{
"search_descriptor": {
"fdn": "ABC*",
"consecutive": null,
"rc_name": "CHICAGO HEIGHTS",
"state": "IL"
}
}
Limiting Search Results
{
"search_descriptor": {
"fdn": "ABC*",
"consecutive": 4,
"city": "Chicago",
"state": "IL"
},
"limit": 50
}
Feature Search
Limits search results to having certain features. For example, you can choose to search for only SMS enabled numbers by limiting has_all_features
to just sms.
{
"search_type": 4,
"search_descriptor": {
"fdn": "ABC*",
"consecutive": 4,
"city": "Chicago",
"state": "IL",
"has_all_features": ["sms"]
},
"limit": 50
}
has_all_features
will return numbers that have BOTH sms and voice.
{
"search_type": 4,
"search_descriptor": {
"fdn": "ABC*",
"consecutive": 4,
"city": "Chicago",
"state": "IL",
"has_any_features": ["sms", "voice"]
},
"limit": 50
}
has_any_features
will return numbers that have either sms or voice.
Possible features: sms, 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:
{
"search_descriptor": {
"npa": "312",
"best_effort": false
}
}