Advanced Number Search

This guide will cover everything you need to know about performing advanced number searches.

When performing your search, * matches any character; TELE matches "8353"; && matches "11", "22", etc. You can also use consecutive to search for numbers in sequence e.g. xxx-xxx-1234, xxx-xxx-1235.

To show all available filters, see the full documentation here

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "x-api-token: YOUR_API_TOKEN" \
  --data '{"search_descriptor":{"consecutive":4,"city":"Chicago","state":"IL","has_any_features":["sms","voice"]},"search_type":4,"limit":1}' \
  "https://api.telnyx.com/origination/number_searches"

Note: Sample result can vary depending on the available numbers at a given moment.

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

Advanced 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": "8*",
    "nxx": "4&&",
    "fdn": "ABC*",
    "consecutive": 4
  }
}

Advanced Region

Search for numbers in a region with additional filters. The FDN (Fixed Dialer Number) refers to the 4 digits that follow the NXX. Each DID is typically made up of NPA-NXX-FDN

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

Advanced Rate Center

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

Limiting Search Results

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

Feature Search

Limits 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": 4,
  "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": 4,
  "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, voice, fax

Disabling Best Effort Search

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