Buying a toll free number with Twilio – Twilio Support

Note: All US Toll-Free numbers must be verified before they can be used for sms messaging in the U.S. and Canada. Toll-Free numbers will be blocked from messaging until they've been submitted for verification. To learn more see Toll-Free Message Verification for US/Canada.

Objective

Twilio allows you to purchase a toll-free phone number via Console or the REST API. We also allow users to port in an existing toll-free phone number. This guide will walk users through the steps for each method.

Notice: While Twilio has a wide range of available toll free phone numbers, we often do not have 1-800 prefix US-based numbers in stock due to low availability. To learn more about exhausted prefixes see Are there areas where Twilio does not provide phone numbers?

Product

Phone Numbers

Procedure

Search for and Purchase a toll-free phone number via the Console

Access the Buy a Number page in Console.
Click Show Advanced Search.
Enter the criteria for the phone number you need, and then click Search.
- Country: Select the desired country from the drop-down menu.
- Number (Optional): Enter any desired prefix and number strings to start the phone number.
- Capabilities: Select your service needs for this number.
- Type: Select only Toll-Free.
- Address Requirement: Select the desired address requirement options.
The search results will be displayed. Click Buy to purchase a phone number for your current account or sub-account.

Note: Many countries require Regulatory Compliance information for Phone Number ownership. Requests to provision phone numbers with these regulations will be required to select or add the required documentation after clicking Buy in Console. To see which countries and phone number types are affected by these requirements, please see our Phone Number Regulations site.

After your phone number has been successfully provisioned, your account will be charged for the full monthly price of the phone number. For more details, please see How much does a phone number cost.

Search for and Purchase a toll-free phone number via the REST API

Twilio phone numbers can also be searched and purchased programmatically using REST API requests.

First, users must make an HTTP GET request to the AvailablePhoneNumberTollFree resource to find available phone numbers. Here’s an example cURL script:

curl -X GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/TollFree.json \
  -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

Once the desired available toll-free phone number has been identified, users can provision it on their account or subaccount with an HTTP POST request to the IncomingPhoneNumber resource. Here’s an example cURL script:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.json \
  --data-urlencode "PhoneNumber=+1800XXXXXXX" \
  --data-urlencode "AddressSid=ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

For more details, see Using the REST API to Search for and Buy Twilio Phone Numbers.

Port-in an existing toll-free phone number

Twilio may be able to port-in existing toll free phone numbers from other carriers. To get started, you’ll need request the phone number be ported in to Twilio via Console. For more information, see How do I submit a port request to Twilio.

Notice: Some services may offer expedited porting to Twilio through a Transfer to RespOrg option. To take advantage of expedited porting, please enter TWI01 as the RespOrg.

Toll-Free Message Verification for US/Canada

Any newly-purchased Toll-Free number on Twilio in the US/Canada will need to be verified or it may experience service interruptions. Customers with existing Toll-Free numbers already on their accounts have until September 30, 2022 to verify traffic for those numbers, however unverified numbers have always had a higher risk of being filtered. We highly recommend that Toll-Free numbers are verified as soon as possible to avoid filtering. For more details on the verification process please see Toll-Free Message Verification for US/Canada.