This is the API V2 documentation. To switch out of beta revert back to our API V1.

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 (meant to be used after `national_destination_code` filter has been set).

filter[phone_number][ends_with]
string
optional

Filter numbers ending with a pattern.

filter[phone_number][contains]
string
optional

Filter numbers containing a pattern.

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[number_type]
string
optional

Filter phone numbers by number type.

Example: "toll-free"
Options: [ "toll-free" ]
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"
      },
      "phone_number": "+19705555098",
      "quickship": true,
      "record_type": "available_phone_number",
      "region_information": [
        {
          "region_name": "US",
          "region_type": "country_code"
        }
      ],
      "regulatory_requirements": [
        {
          "description": "Requirement for providing Proof of Address.",
          "field_type": "address",
          "label": "Proof of Address",
          "requirement_type": "end user proof of address"
        }
      ],
      "reservable": true,
      "vanity_format": ""
    }
  ],
  "meta": {
    "best_effort_results": 50,
    "total_results": 100
  }
}

Was this section helpful?