Sample - Twilio API
GET/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/TollFree.json

List available toll-free phone numbers

Lists available toll-free phone numbers for a specified country and account. Use capability, location, address-requirement, and pagination filters to narrow the results returned for the toll-free number type.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

23 parameters
AccountSidstringrequired
The 34-character SID of the Account requesting available toll-free phone numbers, matching the `AC` prefix and 32 hexadecimal characters.
CountryCodestringrequired
The ISO-3166-1 country code from which to search for available toll-free phone numbers.
AreaCodeintegeroptional
The area code to use when filtering numbers; applies only to numbers in the US and Canada.
Containsstringoptional
A 2- to 16-character phone-number matching pattern using digits, non-diacritic Latin letters, and the supported `*`, `%`, `+`, and `$` meta-characters.
SmsEnabledbooleanoptional
Filter for numbers that can receive text messages. Use `true` or `false`.
MmsEnabledbooleanoptional
Filter for numbers that can receive MMS messages. Use `true` or `false`.
VoiceEnabledbooleanoptional
Filter for numbers that can receive calls. Use `true` or `false`.
ExcludeAllAddressRequiredbooleanoptional
Exclude numbers that require an Address. Use `true` or `false`; defaults to `false` when omitted.
ExcludeLocalAddressRequiredbooleanoptional
Exclude numbers that require a local Address. Use `true` or `false`; defaults to `false` when omitted.
ExcludeForeignAddressRequiredbooleanoptional
Exclude numbers that require a foreign Address. Use `true` or `false`; defaults to `false` when omitted.
Betabooleanoptional
Include numbers that are new to the platform. Use `true` or `false`; defaults to `true` when omitted.
NearNumberstringoptional
A phone number used to find geographically close numbers within the search distance; use phone-number format.
NearLatLongstringoptional
A `lat,long` pair used to find geographically close numbers in the US or Canada.
Distanceintegeroptional
The search radius in miles for a near-number query. Must be no greater than 500 and defaults to 25 when omitted.
InPostalCodestringoptional
Limit results to a postal code, or search the same postal code as the supplied phone number.
InRegionstringoptional
Limit results to a region, state, or province, or search the same region as the supplied phone number.
InRateCenterstringoptional
Limit results to a rate center, or search the same rate center as the supplied phone number; requires `InLata`.
InLatastringoptional
Limit results to a local access and transport area, or search the same LATA as the supplied phone number.
InLocalitystringoptional
Limit results to a locality or city, or search the same locality as the supplied phone number.
FaxEnabledbooleanoptional
Filter for numbers that can receive faxes. Use `true` or `false`.
PageSizeintegeroptional
The number of resources per page. Must be between 1 and 1000 and defaults to 50 when omitted.
Pageintegeroptional
The page index for client state. Must be zero or greater.
PageTokenstringoptional
The pagination token provided by the API.

1 status code
200Returns a paginated collection of available toll-free phone numbers, including pagination links, indexes, and number details such as location, capabilities, and address requirements.
endintegeroptional
first_page_uristringoptional
next_page_uristringoptional
pageintegeroptional
page_sizeintegeroptional
previous_page_uristringoptional
startintegeroptional
uristringoptional
available_phone_numbersarray<object>optional

Error handling

AccountSid must be a 34-character Account SID matching the AC prefix and 32 hexadecimal characters, and CountryCode must use an ISO-3166-1 country code. PageSize must be between 1 and 1000, Page must be zero or greater, and Contains must follow the documented matching-pattern rules.