Skip to contentSkip to navigationSkip to topbar
Rate this page:
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(link takes you to an external page) for country availability.


AvailablePhoneNumberTollFree Properties

availablephonenumbertollfree-properties page anchor
Property nameTypePIIDescription
friendly_namestring<phone-number>
Not PII

A formatted version of the phone number.


phone_numberstring<phone-number>

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


latastring

The LATA(link takes you to an external page) of this phone number. Available for only phone numbers from the US and Canada.


localitystring

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


rate_centerstring

The rate center(link takes you to an external page) of this phone number. Available for only phone numbers from the US and Canada.


latitudenumber

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


longitudenumber

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


regionstring

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

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>

address_requirementsstring

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

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


capabilitiesobject<phone-number-capabilities>

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.


Read multiple AvailablePhoneNumberTollFree resources

read-multiple-availablephonenumbertollfree-resources page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/TollFree.json

Path parameters

path-parameters page anchor
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(link takes you to an external page) country code of the country from which to read phone numbers.

Property nameTypeRequiredPIIDescription
AreaCodeintegerOptional

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


ContainsstringOptional

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.


SmsEnabledbooleanOptional

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


MmsEnabledbooleanOptional

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


VoiceEnabledbooleanOptional

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


ExcludeAllAddressRequiredbooleanOptional

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


ExcludeLocalAddressRequiredbooleanOptional

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


ExcludeForeignAddressRequiredbooleanOptional

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


BetabooleanOptional

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.


NearLatLongstringOptional

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


DistanceintegerOptional

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.


InPostalCodestringOptional

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.


InRegionstringOptional

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.


InRateCenterstringOptional

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.


InLatastringOptional

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


InLocalitystringOptional

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


FaxEnabledbooleanOptional

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


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.

Find any toll-free number

find-any-toll-free-number page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
import twilio from "twilio";
_14
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = twilio(accountSid, authToken);
_14
_14
const tollFrees = await client
_14
.availablePhoneNumbers("US")
_14
.tollFree.list({ limit: 20 });
_14
_14
tollFrees.forEach((t) => console.log(t.friendlyName));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": true,
_24
"voice": true
_24
},
_24
"friendly_name": "(800) 100-0052",
_24
"iso_country": "US",
_24
"lata": null,
_24
"latitude": null,
_24
"locality": null,
_24
"longitude": null,
_24
"phone_number": "+18001000052",
_24
"postal_code": null,
_24
"rate_center": null,
_24
"region": null
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US/TollFree.json"
_24
}

Find toll-free number by string

find-toll-free-number-by-string page anchor

Find toll-free phone numbers that start with 866, followed by any three digits, then the string EPIC.

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

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
import twilio from "twilio";
_15
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = twilio(accountSid, authToken);
_15
_15
const tollFrees = await client.availablePhoneNumbers("US").tollFree.list({
_15
contains: "866***EPIC",
_15
limit: 20,
_15
});
_15
_15
tollFrees.forEach((t) => console.log(t.friendlyName));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": true,
_24
"voice": true
_24
},
_24
"friendly_name": "(800) 100-0052",
_24
"iso_country": "US",
_24
"lata": null,
_24
"latitude": null,
_24
"locality": null,
_24
"longitude": null,
_24
"phone_number": "+18001000052",
_24
"postal_code": null,
_24
"rate_center": null,
_24
"region": null
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US/TollFree.json"
_24
}

Find toll-free number by pattern

find-toll-free-number-by-pattern page anchor

Find toll-free phone numbers in the 800 area code that contain the pattern 'KYLO'

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

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
import twilio from "twilio";
_16
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = twilio(accountSid, authToken);
_16
_16
const tollFrees = await client.availablePhoneNumbers("US").tollFree.list({
_16
areaCode: 800,
_16
contains: "KYLO",
_16
limit: 20,
_16
});
_16
_16
tollFrees.forEach((t) => console.log(t.friendlyName));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": true,
_24
"voice": true
_24
},
_24
"friendly_name": "(800) 100-0052",
_24
"iso_country": "US",
_24
"lata": null,
_24
"latitude": null,
_24
"locality": null,
_24
"longitude": null,
_24
"phone_number": "+18001000052",
_24
"postal_code": null,
_24
"rate_center": null,
_24
"region": null
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers/US/TollFree.json"
_24
}


Rate this page: