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 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: "local"
Options: [ "toll-free", "national", "mobile", "local" ]
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
Responses
200

An array of phone numbers. This is not paginated. The limit filter can be used to control the amount of results returned.

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?was-this-page-helpful