Skip to content Skip to navigation Skip to topbar

On this page

AvailablePhoneNumber TollFree resource

The AvailablePhoneNumberTollFree resource lets you search for toll-free 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.

(information)

Info

Once you've found an available number you want to purchase, make an HTTP POST request to the IncomingPhoneNumbers list resource passing the number as the 'PhoneNumber' parameter.

We work hard to keep a wide variety of numbers in stock at all times. See our pricing pages for country availability.

TollFree Properties

Property nameTypeRequiredDescriptionChild properties

friendly_namestring<phone-number>

Optional

A formatted version of the phone number.

phone_numberstring<phone-number>

Optional

The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.

latastring

Optional

The LATA of this phone number. Available for only phone numbers from the US and Canada.

localitystring

Optional

The locality or city of this phone number's location.

rate_centerstring

Optional

The rate center of this phone number. Available for only phone numbers from the US and Canada.

latitudenumber

Optional

The latitude of this phone number's location. Available for only phone numbers from the US and Canada.

longitudenumber

Optional

The longitude of this phone number's location. Available for only phone numbers from the US and Canada.

regionstring

Optional

The two-letter state or province abbreviation of this phone number's location. Available for only phone numbers from the US and Canada.

postal_codestring

Optional

The postal or ZIP code of this phone number's location. Available for only phone numbers from the US and Canada.

iso_countrystring<iso-country-code>

Optional

The ISO country code of this phone number.

address_requirementsstring

Optional

The type of Address resource the phone number requires. Can be: none, any, local, or foreign. none means no address is required. any means an address is required, but it can be anywhere in the world. local means an address in the phone number's country is required. foreign means an address outside of the phone number's country is required.

betaboolean

Optional

Whether the phone number is new to the Twilio platform. Can be: true or false.

capabilitiesobject<phone-number-capabilities>

Optional

The set of Boolean properties that indicate whether a phone number can receive calls or messages. Capabilities are: Voice, SMS, and MMS and each capability can be: true or false.

Show child properties for capabilities

Read multiple AvailablePhoneNumberTollFree resources

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

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

The SID of the Account requesting the AvailablePhoneNumber resources.

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

CountryCodestring<iso-country-code>required

The ISO-3166-1 country code of the country from which to read phone numbers.

Query parameters

Property nameTypeRequiredPIIDescription

AreaCodeinteger

Optional

The area code of the phone numbers to read. Applies to only phone numbers in the US and Canada.

Containsstring

Optional

The pattern on which to match phone numbers. Valid characters are *, 0-9, a-z, and A-Z. The * character matches any single digit. For examples, see Example 2 and Example 3. If specified, this value must have at least two characters.

SmsEnabledboolean

Optional

Whether the phone numbers can receive text messages. Can be: true or false.

MmsEnabledboolean

Optional

Whether the phone numbers can receive MMS messages. Can be: true or false.

VoiceEnabledboolean

Optional

Whether the phone numbers can receive calls. Can be: true or false.

ExcludeAllAddressRequiredboolean

Optional

Whether to exclude phone numbers that require an Address. Can be: true or false and the default is false.

ExcludeLocalAddressRequiredboolean

Optional

Whether to exclude phone numbers that require a local Address. Can be: true or false and the default is false.

ExcludeForeignAddressRequiredboolean

Optional

Whether to exclude phone numbers that require a foreign Address. Can be: true or false and the default is false.

Betaboolean

Optional

Whether to read phone numbers that are new to the Twilio platform. Can be: true or false and the default is true.

NearNumberstring<phone-number>

Optional

Given a phone number, find a geographically close number within distance miles. Distance defaults to 25 miles. Applies to only phone numbers in the US and Canada.

NearLatLongstring

Optional

Given a latitude/longitude pair lat,long find geographically close numbers within distance miles. Applies to only phone numbers in the US and Canada.

Distanceinteger

Optional

The search radius, in miles, for a near_ query. Can be up to 500 and the default is 25. Applies to only phone numbers in the US and Canada.

InPostalCodestring

Optional

Limit results to a particular postal code. Given a phone number, search within the same postal code as that number. Applies to only phone numbers in the US and Canada.

InRegionstring

Optional

Limit results to a particular region, state, or province. Given a phone number, search within the same region as that number. Applies to only phone numbers in the US and Canada.

InRateCenterstring

Optional

Limit results to a specific rate center, or given a phone number search within the same rate center as that number. Requires in_lata to be set as well. Applies to only phone numbers in the US and Canada.

InLatastring

Optional

Limit results to a specific local access and transport area (LATA). Given a phone number, search within the same LATA as that number. Applies to only phone numbers in the US and Canada.

InLocalitystring

Optional

Limit results to a particular locality or city. Given a phone number, search within the same Locality as that number.

FaxEnabledboolean

Optional

Whether the phone numbers can receive faxes. Can be: true or false.

PageSizeinteger

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

The page token. This is provided by the API.

Find any toll-free number

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 listAvailablePhoneNumberTollFree() {
11  const tollFrees = await client
12    .availablePhoneNumbers("US")
13    .tollFree.list({ limit: 20 });
14
15  tollFrees.forEach((t) => console.log(t.friendlyName));
16}
17
18listAvailablePhoneNumberTollFree();

Output

1{
2  "available_phone_numbers": [
3    {
4      "address_requirements": "none",
5      "beta": false,
6      "capabilities": {
7        "mms": true,
8        "sms": true,
9        "voice": true
10      },
11      "friendly_name": "(800) 100-0052",
12      "iso_country": "US",
13      "lata": null,
14      "latitude": null,
15      "locality": null,
16      "longitude": null,
17      "phone_number": "+18001000052",
18      "postal_code": null,
19      "rate_center": null,
20      "region": null
21    }
22  ],
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US/TollFree.json"
24}

Find toll-free number by string

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 listAvailablePhoneNumberTollFree() {
11  const tollFrees = await client.availablePhoneNumbers("US").tollFree.list({
12    contains: "866***EPIC",
13    limit: 20,
14  });
15
16  tollFrees.forEach((t) => console.log(t.friendlyName));
17}
18
19listAvailablePhoneNumberTollFree();

Output

1{
2  "available_phone_numbers": [
3    {
4      "address_requirements": "none",
5      "beta": false,
6      "capabilities": {
7        "mms": true,
8        "sms": true,
9        "voice": true
10      },
11      "friendly_name": "(800) 100-0052",
12      "iso_country": "US",
13      "lata": null,
14      "latitude": null,
15      "locality": null,
16      "longitude": null,
17      "phone_number": "+18001000052",
18      "postal_code": null,
19      "rate_center": null,
20      "region": null
21    }
22  ],
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US/TollFree.json"
24}

Find toll-free number by pattern

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 listAvailablePhoneNumberTollFree() {
11  const tollFrees = await client.availablePhoneNumbers("US").tollFree.list({
12    areaCode: 800,
13    contains: "KYLO",
14    limit: 20,
15  });
16
17  tollFrees.forEach((t) => console.log(t.friendlyName));
18}
19
20listAvailablePhoneNumberTollFree();

Output

1{
2  "available_phone_numbers": [
3    {
4      "address_requirements": "none",
5      "beta": false,
6      "capabilities": {
7        "mms": true,
8        "sms": true,
9        "voice": true
10      },
11      "friendly_name": "(800) 100-0052",
12      "iso_country": "US",
13      "lata": null,
14      "latitude": null,
15      "locality": null,
16      "longitude": null,
17      "phone_number": "+18001000052",
18      "postal_code": null,
19      "rate_center": null,
20      "region": null
21    }
22  ],
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US/TollFree.json"
24}