Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

AvailablePhoneNumber resource


The subresources of the AvailablePhoneNumber resource lets you search for local, toll-free and mobile phone numbers that are available for you to purchase. You can search for phone numbers that match a pattern, are in a certain country, are in certain area code (NPA) or exchange (NXX) or are in a specific geography.

You cannot make requests directly to AvailablePhoneNumber instance resources. Instead, to find available numbers, make a request to one of the subresources:

(information)

Info

Once you've found a number you'd like to purchase (also referred to as provisioning a number or buying the number), you can do so using the Incoming Phone Numbers API.


Supported Countries and Types

supported-countries-and-types page anchor

You can query the AvailablePhoneNumber resource to get a list of subresources available for your account by ISO Country. For full information about our phone number support, see our Phone Number CSV(link takes you to an external page) or the FAQ(link takes you to an external page). Each instance of the resource will have the following properties.

Property nameTypePIIDescription
country_codestring<iso-country-code>
Not PII

The ISO-3166-1(link takes you to an external page) country code of the country.


countrystring

The name of the country.


uristring<uri>

The URI of the Country resource, relative to https://api.twilio.com.


betaboolean

Whether all phone numbers available in the country are new to the Twilio platform. true if they are and false if all numbers are not in the Twilio Phone Number Beta program.


subresource_urisobject<uri-map>

A list of related AvailablePhoneNumber resources identified by their URIs relative to https://api.twilio.com.


Fetch a specific country

fetch-a-specific-country page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}.json

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required

The SID of the Account requesting the available phone number Country resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

CountryCodestring<iso-country-code>required

The ISO-3166-1(link takes you to an external page) country code of the country to fetch available phone number information about.

Fetch a specific country

fetch-a-specific-country-1 page anchor

Fetches the subresources available for the US

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.availablePhoneNumbers('US')
_10
.fetch()
_10
.then(available_phone_number_country => console.log(available_phone_number_country.countryCode));

Output

_10
{
_10
"beta": null,
_10
"country": "United States",
_10
"country_code": "US",
_10
"subresource_uris": {
_10
"local": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json",
_10
"toll_free": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/TollFree.json"
_10
},
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US.json"
_10
}


Read a list of countries

read-a-list-of-countries page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers.json

Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required

The SID of the Account requesting the available phone number Country resources.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
PageSizeintegerOptional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

Gets the subresources available for all supported countries

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.availablePhoneNumbers
_10
.list({limit: 20})
_10
.then(availablePhoneNumbers => availablePhoneNumbers.forEach(a => console.log(a.countryCode)));

Output

_15
{
_15
"countries": [
_15
{
_15
"beta": false,
_15
"country": "Denmark",
_15
"country_code": "DK",
_15
"subresource_uris": {
_15
"local": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/DK/Local.json"
_15
},
_15
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/DK.json"
_15
}
_15
],
_15
"end": 1,
_15
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers.json"
_15
}


Rate this page: