Skip to content Skip to navigation Skip to topbar

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

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 or the FAQ. Each instance of the resource will have the following properties.

Property nameTypeRequiredDescriptionChild properties

country_codestring<iso-country-code>

Optional

Not PII

The ISO-3166-1 country code of the country.

countrystring

Optional

Not PII

The name of the country.

uristring<uri>

Optional

Not PII

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

betaboolean

Optional

Not PII

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>

Optional

Not PII

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

Fetch a specific country

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}.json

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

Not PII

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

Not PII

The ISO-3166-1 country code of the country to fetch available phone number information about.

Fetch a specific country

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchAvailablePhoneNumberCountry() {
11  const availablePhoneNumber = await client.availablePhoneNumbers("US").fetch();
12
13  console.log(availablePhoneNumber.countryCode);
14}
15
16fetchAvailablePhoneNumberCountry();

Output

1{
2  "beta": false,
3  "country": "United States",
4  "country_code": "US",
5  "subresource_uris": {
6    "local": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US/Local.json",
7    "toll_free": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US/TollFree.json"
8  },
9  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US.json"
10}

Read a list of countries

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers.json

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

Not PII

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

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

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeinteger

Optional

Not PII

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

Not PII

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

Minimum: 0

PageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Read a list of countries

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listAvailablePhoneNumberCountry() {
11  const availablePhoneNumbers = await client.availablePhoneNumbers.list({
12    limit: 20,
13  });
14
15  availablePhoneNumbers.forEach((a) => console.log(a.countryCode));
16}
17
18listAvailablePhoneNumberCountry();

Output

1{
2  "countries": [
3    {
4      "beta": false,
5      "country": "Denmark",
6      "country_code": "DK",
7      "subresource_uris": {
8        "local": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/DK/Local.json",
9        "toll_free": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/DK/TollFree.json"
10      },
11      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/DK.json"
12    },
13    {
14      "beta": false,
15      "country": "Australia",
16      "country_code": "AU",
17      "subresource_uris": {
18        "local": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/AU/Local.json",
19        "mobile": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/AU/Mobile.json",
20        "toll_free": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/AU/TollFree.json"
21      },
22      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/AU.json"
23    }
24  ],
25  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers.json"
26}