Phone Number Search

List available phone numbers

Changed on

Searches the Telnyx inventory for available phone numbers. Filters support number patterns, location, number type, features, reservability, and other inventory constraints; the response includes matching numbers and search metadata.

get/available_phone_numbers

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/available_phone_numbers
  • Auth: HTTP bearer

Query parameters

localitystring

Filter phone numbers by city.

administrative_areastring

Find numbers in a particular US state or CA province.

country_codestring

Filter phone numbers by country.

national_destination_codestring

Filter by the national destination code of the number.

rate_centerstring

Filter phone numbers by rate center. This filter is only applicable to USA and Canada numbers.

phone_number_type'local' | 'toll_free' | 'mobile' | 'national' | 'shared_cost'

Filter phone numbers by number type.

featuresstring[]

Filter phone numbers with specific features.

limitinteger

Limits the number of results.

best_effortboolean

Filter to determine if best effort results should be included. Only available in USA/CANADA.

quickshipboolean

Filter to exclude phone numbers that need additional time after to purchase to activate. Only applicable for +1 toll_free numbers.

reservableboolean

Filter to ensure only numbers that can be reserved are included in the results.

exclude_held_numbersboolean

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

Consolidated filter parameter (deepObject style). Originally: filter[phone_number], filter[locality], filter[administrative_area], filter[country_code], filter[national_destination_code], filter[rate_center], filter[phone_number_type], filter[features], filter[limit], filter[best_effort], filter[quickship], filter[reservable], filter[exclude_held_numbers]

Response

Successful response with a list of available phone numbers.

Example response

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

Changes

  • 19db5ee4ec59Revision changes
    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • a6a61a29ecddRevision changes
    • breaking

      the // response's property type changed from string to integer, and format from no format to int32 for status

    • breaking

      the // response's property type changed from string to integer, and format from no format to int32 for status

    • breaking

      the // response's property type changed from string to integer, and format from no format to int32 for status

    • breaking

      the // response's property type changed from string to integer, and format from no format to int32 for status

    • breaking

      the // response's property type changed from string to integer, and format from no format to int32 for status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status