Portal Search Guide

There are a variety of filters to help you find the perfect phone number.

Below is a list of the search filters we made available in the Portal with examples of when you may use them. At the end of this guide is a couple of “best practices” for searching as well.

You can find the API reference for the GET v2/available_phone_numbers endpoint here.

Feature: Phone numbers have varying capabilities. Filter for phone numbers that have the features to satisfy your use case. I.e. “sms” will return phone numbers that support SMS, “emergency” will return phone numbers capable of placing emergency calls, etc.

Type: Filter for a specific type of phone number. I.e. “local” will return local/geographic phone numbers, “toll-free” will return toll-free phone numbers only, etc.

Area Code: Search for phone numbers in a given area code. I.e. “205” will return phone numbers with a “205” area code

City / Region: Search for phone numbers in a given city / region / rate center. I.e. “Boston” would return phone numbers in or near Boston, MA.

[US/CA only] State / Province: Search for phone numbers in a given state / province. I.e. filtering for “MA” will return phone numbers in Massachusetts.

Starts with: “56” will return numbers starting with “56”, i.e. +1-312-562-0011. Couple of things to note:

• Never include the country code (i.e. "+1") in the search filter.
• If you are using the Area Code filter in conjunction with the Starts with filter, do not include the area code digits in the starts with filter. I.e. if you wanted to find +1-312-562-0011, you would use Area Code = 312 and Starts With = 562.
• If you are not using the Area Code filter, include the area code digits in the starts with filter. I.e. if you wanted to find +1-312-562-0011, you would use Starts With = 312562.

Ends with: “356” will return numbers ending with “356”, i.e. +1-312-562-0356.

Contains: “56” will return numbers matching “5” and ”6” anywhere, i.e. +1-312-622-0533.

Consecutive Numbers: Range of successive phone numbers. I.e. entering “3” will return +1-312-562-0011, +1-312-562-0012, and +1-312-562-0013 in the search results

Results Limit: Define the maximum quantity of phone numbers in the search results. I.e. “2” will return a maximum of 2 phone numbers in your search results

[US / CA only] Best Effort: Telnyx may not have phone numbers that meet your exact search criteria. If that’s the case and “Best Effort” is toggled on, Telnyx will return similar results that meet some of your criteria.

[US toll-free only] Quickship: When “Quickship” is toggled on, the toll-free phone numbers returned in search are pre-provisioned and ready for immediate activation. When “Quickship” is toggled off, a phone number may be returned that is not pre-provisioned. If that phone number is purchased, it can take up to 2 business days for provisioning to complete and the phone number to be usable. If the filter is toggled on and you are searching for something that isn’t a US toll-free phone number, then the filter will be ignored.

Reservable Numbers: Returns phone numbers that are eligible to be reserved. When a phone number is reserved, you will have exclusive rights to search and order the phone number for a period of 30 minutes. More details here.

Exclude Held Numbers: A phone number can be on “hold” in two instances. Either the phone number was recently deleted and is in the process of being recycled. Or the phone number was placed on hold by Telnyx’s Number Ops team for you to search and purchase. Enabling this filter will exclude any phone numbers in a “hold” status from the search results.

Telnyx Bundle: Only returns phone numbers that are eligible for Telnyx Bundles.

The only required search filter is “country_code”. The “phone_number_type” filter isn’t required, but we generally recommend using it. The remaining filters can be used to further narrow down your search results as needed.

If you need phone numbers that are emergency capable, please include the features filter with emergency as a feature.

If you need phone numbers that are SMS capable, please include the features filter with sms as a feature. Any phone number with sms as a feature should be capable and ready to immediately leverage SMS.

Wildcard characters (*, %, etc.) are not supported in any of the filters. If a wildcard character is included in a filter, the search will yield 0 results.

For US toll-free phone numbers, we recommend using the quickship filter in your initial search requests. In doing so, you will be purchasing a phone number that is usable immediately. If you can’t find what you are looking for, you can disable the quickship filter to expand the possible search results. Just be aware that it could take up to 2 business days for a non-quickship toll-free phone number to be active after purchase.