Open SidemenuAPI Reference
API Reference
Close Sidemenu

Number Search

List available phone numberslistAvailablePhoneNumbers

get https://api.telnyx.com/v2/available_phone_numbers

List available phone numbers

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[rate_center][]=CHICAGO%20HEIGHTS"
Parameters
In query
filter[phone_number][starts_with]
string
optional

Filter numbers starting with a pattern (exclude NDC from start of this filter if used with `national_destination_code` filter).

filter[phone_number][ends_with]
string
optional

Filter numbers ending with a pattern (max length of 4 digits if used with `national_destination_code` filter).

filter[phone_number][contains]
string
optional

Filter numbers containing a pattern (must be used with `national_destination_code` filter and only searches within last 4 digits).

filter[locality]
string
optional

Filter phone numbers by city.

filter[administrative_area]
string
optional

Filter phone numbers by US state/CA province.

Example: "IL"
filter[country_code]
string
optional

Filter phone numbers by ISO alpha-2 country code.

Example: "US"
filter[national_destination_code]
string
optional

Filter by the national destination code of the number. This filter is only applicable to North American numbers.

filter[rate_center]
string
optional

Filter phone numbers by NANP rate center. This filter is only applicable to North American numbers.

Example: "CHICAGO HEIGHTS"
filter[phone_number_type]
string
optional

Filter phone numbers by number type.

Example: "local"
Options: [ "local", "toll_free", "mobile", "national", "shared_cost", "landline" ]
filter[features]
array of string
optional

Filter if the phone number should be used for voice, fax, mms, sms, emergency.

Example: "voice,sms"
Options: [ "sms", "mms", "voice", "fax", "emergency" ]
filter[limit]
integer
optional

Limits the number of results.

Example: 100
filter[best_effort]
boolean
optional

Filter to determine if best effort results should be included.

filter[quickship]
boolean
optional

Filter to exclude phone numbers that need additional time after to purchase to receive phone calls.

Example: true
filter[reservable]
boolean
optional

Filter to exclude phone numbers that cannot be reserved before purchase.

Example: true
filter[exclude_held_numbers]
boolean
optional

Filter to exclude phone numbers that are currently on hold for your account.

Responses
200

Successful response with a list of available phone numbers.

default

Unexpected error

Success Response
{
  "data": [
    {
      "best_effort": false,
      "cost_information": {
        "currency": "USD",
        "monthly_cost": "6.54",
        "upfront_cost": "3.21"
      },
      "features": [
        {
          "name": "sms"
        },
        {
          "name": "voice"
        }
      ],
      "phone_number": "+19705555098",
      "quickship": true,
      "record_type": "available_phone_number",
      "region_information": [
        {
          "region_name": "US",
          "region_type": "country_code"
        }
      ],
      "reservable": true,
      "vanity_format": ""
    }
  ],
  "meta": {
    "best_effort_results": 50,
    "total_results": 100
  }
}

Was this section helpful?