List available phone numbers

GET 
/available_phone_numbers

List available phone numbers

Query Parameters

filter object

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]

200: Successful response with a list of available phone numbers.

application/json

• Schema
• Example (from schema)

Schema

data

object[]

Array [

record_type string

Possible values: [available_phone_number]

phone_number string

vanity_format string

best_effort boolean

Specifies whether the phone number is an exact match based on the search criteria or not.

quickship boolean

Specifies whether the phone number can receive calls immediately after purchase or not.

reservable boolean

Specifies whether the phone number can be reserved before purchase or not.

region_information

object[]

Array [

region_type string

Possible values: [country_code, rate_center, state, location]

region_name string

]

cost_information

object

upfront_cost string

monthly_cost string

currency string

The ISO 4217 code for the currency.

features

object[]

Array [

name string

]

]

meta

object

total_results integer

best_effort_results integer

{
  "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
  }
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

object[]

Array [

code stringrequired

title stringrequired

detail string

source

object

pointer string

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta

object

url string

URL with additional information on the error.

]

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

Request samples

• cURL

---

curl -L 'https://api.telnyx.com/v2/available_phone_numbers' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Response samples

• 200
• default

---

{
  "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
  }
}

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}