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

Schema

    id stringrequired
    search_type integerrequired

    Default value: 1

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

    limit integerrequired

    Default value: 10

    search_descriptor objectrequired
    status integerrequired

    Default value: 1

    Pending = 1, Complete = 2

    any_best_effort booleanrequired

    Default value: false

    Indicator of whether there are any best effort matches present or not

    result object[]required

400: Bad request

401: Unauthorized

Loading...