Skip to main content

Create a number search

POST 
/origination/number_searches
Search by NPANXX:

"nxx" parameter is optional.

{
"search_descriptor": {
"npa": "301",
"nxx": "359"
}
}
Search by Region:

Search by city and state abbreviation.

{
"search_descriptor": {
"city": "Chicago",
"state": "IL"
}
}

Search by Country:

Specifying a country and city

{
"search_descriptor": {
"city": "Paris",
"country_iso": "FR"
}
}

Specifying a country and area code

{
"search_descriptor": {
"national_destination_code": "17037",
"country_iso": "FR"
}
}
{
"search_descriptor": {
"has_all_features": ["voice", "sms", "fax"],
"national_destination_code": "301",
"country_iso": "US"
}
}
Search by Tollfree prefix:

"800", "888", etc...

{
"search_descriptor":{
"country_iso":"US",
"npa":"877"
},
"search_type":2
}
Search by multiple Tollfree prefixes:
{
"search_descriptor": {
"country_iso": "US",
"national_destination_codes": ["800", "888"]
},
"search_type": 2
}

Search Vanity Tollfree numbers with placement start:

{
"search_descriptor": {
"placement": "start",
"vanity_string": "TELNYX",
"national_destination_code": "all",
"trailing_digits": 2,
"country_iso": "US"
},
"search_type": 2
}

Search Vanity Tollfree numbers with placement any:

{
"search_descriptor": {
"placement": "any",
"vanity_string": "TELNYX",
"national_destination_code": "all",
"trailing_digits": 2,
"country_iso": "US"
},
"search_type": 2
}

Search Vanity Tollfree numbers with placement end:

{
"search_descriptor": {
"placement": "end",
"vanity_string": "TELNYX",
"national_destination_code": "all",
"trailing_digits": 2,
"country_iso": "US"
},
"search_type": 2
}
Search by advanced parameters:

* matches any character; TELE matches "8353"; && matches "11", "22", etc...

Use consecutive to search for numbers in sequence, such as xxx-xxx-1234, xxx-xxx-1235

Advanced NPA/NXX exp:

{
"search_descriptor": {
"npa": "8*",
"nxx": "4&&",
"fdn": "ABC*",
"consecutive": 4
}
}

Advanced REGION exp:

{
"search_descriptor": {
"fdn": "ABC*",
"consecutive": 4,
"city": "Chicago",
"state": "IL"
}
}

Advanced RATE CENTER exp:

{
"search_descriptor": {
"fdn": "ABC*",
"consecutive": null,
"rc_name": "CHICAGO HEIGHTS",
"state": "IL"
}
}
Limiting search results:

To limit the number of search results, use the limit key:

{
"search_descriptor": {
"fdn": "ABC*",
"consecutive": 4,
"city": "Chicago",
"state": "IL"
},
"limit": 50
}

To limit 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": 2,
"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": 2,
"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, mms, voice, fax, emergency

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
}
}

Request

Body

required

Number search to add

    search_type integerrequired

    NPA/NXX = 1, Region = 2, Tollfree = 3, Advanced = 4

    search_descriptor objectrequired
    limit integer

Responses

200: NumberSearch response

400: Bad request

401: Unauthorized

Request samples


curl -L 'https://api.telnyx.com/origination/number_searches' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"search_type": 0,
"search_descriptor": {},
"limit": 0
}'

Response samples


{
"id": "string",
"search_type": 1,
"limit": 10,
"search_descriptor": {},
"status": 1,
"any_best_effort": false,
"result": [
{}
]
}