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 hereAPI

Check out the Development Environment Setup guide to acquire your API Key and set up a Telnyx SDK if applicable.

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[locality][]=Chicago&filter[administrative_area][]=IL&filter[features][]=sms&filter[limit][]=2"

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

{
  "data": [
    {
      "best_effort": false,
      "cost_information": {
        "currency": "USD",
        "monthly_cost": "1.00000",
        "upfront_cost": "1.00000"
      },
      "features": [
        {
          "name": "fax"
        },
        {
          "name": "voice"
        },
        {
          "name": "sms"
        }
      ],
      "phone_number": "+18728880024",
      "record_type": "available_phone_number",
      "region_information": [
        {
          "region_name": "US",
          "region_type": "country_code"
        },
        {
          "region_name": "IL",
          "region_type": "state"
        },
        {
          "region_name": "CHICAGO ZONE 02",
          "region_type": "rate_center"
        }
      ],
      "reservable": false,
      "vanity_format": null
    },
    {
      "best_effort": false,
      "cost_information": {
        "currency": "USD",
        "monthly_cost": "1.00000",
        "upfront_cost": "1.00000"
      },
      "features": [
        {
          "name": "fax"
        },
        {
          "name": "voice"
        },
        {
          "name": "sms"
        }
      ],
      "phone_number": "+18728880026",
      "record_type": "available_phone_number",
      "region_information": [
        {
          "region_name": "US",
          "region_type": "country_code"
        },
        {
          "region_name": "IL",
          "region_type": "state"
        },
        {
          "region_name": "CHICAGO ZONE 02",
          "region_type": "rate_center"
        }
      ],
      "reservable": false,
      "vanity_format": null
    }
  ],
  "metadata": {
    "best_effort_results": 0,
    "total_results": 2
  },
  "url": "/v2/available_phone_numbers"
}

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. The FDN (Fixed Dialer Number) refers to the 4 digits that follow the NXX.

Note: *The phone_number filter can only be used once per search. For example, if you want to search for a number that starts with "12" and ends with "AB" you could use a starts_with search passing in the following value "12**AB"

The below search is looking for any digits for the first 3 digits (the NPA), followed by a 2, and then a repeated digit.

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[national_destination_code][]=877&filter[phone_number][starts_with]=***2&&&filter[limit][]=2"

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. FDN can be searched for using the ends_with parameter.

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[locality][]=Chicago&filter[phone_number][ends_with]=ABC*&filter[limit][]=2"

Advanced Rate Center

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[rate_center][]=CHICAGO HEIGHTS&filter[administrative_area][]=IL&filter[limit][]=2"

Limiting Search Results

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[national_destination_code][]=312&filter[limit][]=2"

Feature Search

Limits search results to having certain features. For example, you can choose to search for only SMS enabled numbers by limiting the features parameter to just "sms".

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[features][]=sms&filter[limit][]=2"

You could also search for number with SMS and MMS capabilities.

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[features][]=sms&filter[features][]=mms&filter[limit][]=2"

Possible features: "sms", "mms", "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:

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code][]=US&filter[national_destination_code][]=312&filter[best_effort][]=false&filter[limit][]=2"