This is the current API V1 documentation. Explore our API V2 beta if you’d like to test new features.

Docs
Choose:
cURLPython
cURLPython

Number Searchnumber-search

You can search for numbers by region, number, prefix, rate center, type, or enabled features.

When performing your search, you'll need to specify the "search type", the options for this are NPA/NXX = 1, Region = 2, Tollfree = 3, Advanced = 4.

The example below shows a generic number search for a Chicago phone number.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "x-api-token: API_TOKEN" \
  --header "x-api-user: API_USER" \
  --data '{"search_descriptor":{"city":"Chicago","state":"IL"},"search_type":2,"limit":1}' \
  "https://api.telnyx.com/origination/number_searches"

Sample Responsesample-response

{
  "id": "123-45678-456789",
  "result": [
    {
      "number_vanity": null,
      "upfront_cost": "1.00000",
      "vanity_string": null,
      "monthly_recurring_cost": "1.00000",
      "verification_requirements": [],
      "regional_data": {
        "rate_center": "CHICAGO ZONE 11",
        "state": "IL",
        "country_iso": "US"
      },
      "features": [
        {
          "name": "fax"
        },
        {
          "name": "voice"
        },
        {
          "name": "sms"
        }
      ],
      "number_e164": "+17732490576",
      "reservable": false,
      "currency": "USD",
      "best_effort": false
    }
  ],
  "inexplicit_result": [],
  "search_descriptor": {
    "has_all_features": [],
    "rc_name": null,
    "province": "IL",
    "consecutive": null,
    "national_destination_codes": null,
    "subscriber_number": null,
    "vanity_string": null,
    "postal_code": null,
    "prefix": null,
    "trailing_digits": null,
    "has_any_features": [],
    "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 search requests are detailed below.

Search by NPA/NXXsearch-by-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": "301",
    "nxx": "359"
  }
}

Search by Regionsearch-by-region

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

Search by Countrysearch-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 by Tollfree Prefixsearch-by-tollfree-prefix

"800", "888", etc…

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

Congrats, you’ve just completed your first number search using the Telnyx API.