Managing Phone Numbers Using Twilio's REST API

TechCrunch Disrupt For TechCrunch Disrupt going on this week in New York, Twilio was tasked with building an application that would allow attendees to vote on Startup Battlefield participants. To eliminate cheating or ballot stuffing we decided to give all 2000 attendees their own phone number to text to for voting. This limited voting to only those in attendance.

We’ll go into more detail about why we did it this way in a future post but this requirement highlighted an interesting use case: how do you quickly provision 2000 phone numbers for your app? The answer is the Twilio REST API.

Adding Numbers to Your Account via the REST API

If you’re familiar with making calls via the REST API adding a phone number to your account follows a similar process. You add numbers to your account by making a POST request to either the Local or Toll-free LocalIncomingNumber resource. You can specify which area code you’d like a number for, the voice and SMS URLs and a variety of other options. These API methods are only available for full accounts so if you have a trial account you’ll need to upgrade before you can do this.

For this example I’ll be using the Twilio PHP Helper Library to make things even easier. Let’s start by adding a local number to our account in the 415 area code.



It’s very important to check for errors when adding numbers. If Twilio doesn’t have any phone numbers available in the area code requested you will receive an HTTP Status Code 400 back from the API. If you don’t care which area code your number is in, just omit that parameter and we’ll give you a number from somewhere in the US.

Retrieving Your Numbers

For Startup Battlefield we needed to print each of the 2000 numbers we created on a card to give to attendees. Thankfully the Twilio REST API provides an easy way to get a CSV (comma-separated values) file for any resource. To download a CSV of all your phone numbers, we constructed the proper URL and entered in our web browser (replace ACXXXXX with your Account SID).

When accessing this URL in your browser, you will be prompted for a username and password. Use your Account SID for the username and Auth Token for the password. If you omit the ‘.csv’ at the end you’ll get back a regular XML response that includes paging information. Since we just needed a file we could use in a mail merge, we went with the simpler CSV representation. You can learn more about alternate representations in the Tips & Tricks section of our docs.

More to Come

Startup-battlefield-font-transparentWe’ll be doing a complete write up of the Startup Battlefield voting app in the coming days. We’ll cover the unique requirements of the app and how we went about building it. Stay tuned!