List available phone numbers

gethttps://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.
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. Only available in NANPA countries.
filter[quickship]
boolean
optional
Filter to exclude phone numbers that need additional time after to purchase to receive phone calls. Only available for toll-free numbers.
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 page helpful?