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

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

    result object[]required

400: Bad request

401: Unauthorized

Loading...