Create a number search

POST 
/origination/number_searches

"nxx" parameter is optional.

{
  "search_descriptor": {
    "npa": "301",
    "nxx": "359"
  }
}

Search by city and state abbreviation.

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

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

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

{
   "search_descriptor":{
      "country_iso":"US",
      "npa":"877"
   },
   "search_type":2
}

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

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

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

application/json

Body

required

Number search to add

search_type integerrequired

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

search_descriptor objectrequired
limit integer

200: NumberSearch response

application/json

• Schema
• Example (from schema)

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

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

400: Bad request

401: Unauthorized

Request samples

• cURL

---

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

• 200

---

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