Objective
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.
Product
Phone Numbers
Procedure
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:
- Country Code: The two-letter ISO3166 country code (in all capital letters) for the country of origin.
-
Phone Number Type: The type of phone number you want to provision:
Local
,Mobile
, orTollFree
.
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:
- Line 1 update with your Account SID, the country code, the phone number type, and any additional parameters.
- Line 2 update with your Account SID and Auth Token
For full details on each of the possible parameters, and code samples from our helper libraries, please see the following resources:
- Local Phone Numbers Subresource
- Mobile Phone Numbers Subresource
- Toll Free Phone Numbers Subresource
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:
- Line 1 update with your Account SID
- Line 2 update with the desired available phone number in E.164 formatting
- Line 3 update with a valid Address SID (as needed for regulations)
- Line 4 update with a valid Bundle SID (as needed for regulations)
- Line 5 update with your Account SID and Auth Token
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.