SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Using the REST API to Search for and Buy Twilio Phone Numbers

Twilio allows users to both search for and provision phone numbers via the REST API. This allows users to programmatically add new phone numbers to their Twilio applications as needed. This guide is intended to walk you through the process of searching for and provisioning Twilio phone numbers via the REST API. Continue reading for more details.

Notice: You must upgrade your Twilio account to provision more than one phone number.

Search for Twilio Phone Numbers

You can search for available phone numbers by making an HTTP GET request to the appropriate AvailablePhoneNumbers REST API resource with two required pieces of information:

The API resource will include both of these pieces of information in the URL in the following format:

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

Additional parameters can also be added after the URL to help narrow down your search. Here’s an example cURL script:

curl -X GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json?AreaCode=212 \
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

This example requests the list of local phone numbers available in the US under area code (212).

 

To make this script work for you, make the following updates, and then paste it into a terminal window:

For full details on each of the possible parameters, and code samples from our helper libraries, please see the following resources:

You can use the query string parameters such as SmsEnabled, MmsEnabled or VoiceEnabled in the GET request to filter the list of numbers returned by Twilio to find the phone number with the capabilities you need. The “Capabilities” property is also available for each phone number instance so you can easily tell what capabilities a number carries:

<Capabilities>
    <Voice>true</Voice>
    <SMS>true</SMS>
    <MMS>false</SMS>
</Capabilities>

Provision Twilio Phone Numbers

Twilio Phone Numbers can be provisioned on your account by making an HTTP POST request to the IncomingPhoneNumbers REST API resource. Users have the option of provisioning a specific known available phone number found via Console or the REST API, or they can provision a random available phone number from a specific 3-digit area code (US and Canada only).

Here’s an example cURL script:

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

To make this script work for you, make the following updates, and then paste it into a terminal window:

For full details on each of the possible parameters, and code samples from our helper libraries, please see IncomingPhoneNumber resource (Twilio Docs).

Notice: Many countries require regulatory documentation for phone number compliance. Requests to provision phone numbers with these regulations will be required to include a valid AddressSid and/or BundleSid parameter, or else the request may fail. If you see there are requirements for the country listed on our regulatory site, please see How to Submit a Regulatory Bundle for Phone Number Regulatory Compliance.

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.

Using Console to Search for and Provision Phone Numbers

Twilio's Console site can also be used to search our inventory and buy phone numbers. For full details, please see our article How to Search for and Buy a Twilio Phone Number from Console.

Have more questions? Submit a request
Powered by Zendesk