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 customers 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 project 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:

Provision Twilio Phone Numbers

Twilio Phone Numbers can be provisioned on your project 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=+12125551234" \
--data-urlencode "AddressSid=ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

This example will provision the phone number (212)555-1234 on your Twilio project ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.

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 identity documentation for Phone Number compliance. Requests to provision phone numbers with these regulations will be required to include a valid AddressSid and/or IdentitySid parameter, or else the request may fail. 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 project 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