Look Up Phone Numbers with Twilio's Lookup API

by Kellan Alexander

Have you ever wanted to retrieve additional information about a phone number? Perhaps you'd like to know whether a number is a land or mobile line. Maybe you'd like to know the caller's name or carrier. If you have a Twilio account, you've got access to an API that gives you access to all of this information and more. In this article, you'll learn how to use TextIt's webhook step to retrieve information about a number within a flow. 

Webhooks

A webhook is an HTTP callback: a POST request that occurs when something happens (a simple event notification). A web application implementing webhooks will POST a message to a URL when something happens, and this is exactly what TextIt does when a contact reaches the 'Call Webhook' step in a flow. We can use this special step to make requests to Twilio's Lookup API. 

Setup

First, you'll need a Twilio account. Next, grab the Account SID and Auth Token from its settings page. We'll be plugging these values into the new 'Headers' section of the webhook step. (New to TextIt? Use this guide to connect a Twilio number to your account and start sending). 

Credentials in hand, head over to base64encode.org to apply a special type of encoding that Twilio expects for this sort of request*. Simply input your Account SID and Auth Token separated only by a colon, e.g. ADa19ehc8fb23d2515:d09a32e56d8512685, and click the 'Encode' button. 

*Twilio uses a form of authentication called 'Basic Auth'. Basic Auth requires incoming user credentials to be base64 encoded. 

Copy the output and navigate to your TextIt account. Create a flow, select the 'Call Webhook' RuleSet, click the blue 'Additional Options' link, and create a header whose key is 'Authorization' and value  is 'Basic' plus your encoded Twilio credentials: 

Finally, manipulate to the URL to suit your needs. The expression @contact.tel_e164 will resolve to the active contact's number, but you can change it to another number if necessary. You can also change the 'type' query parameter to be 'caller-name'. 

https://lookups.twilio.com/v1/PhoneNumbers/@contact.tel_e164?Type=carrier

Results


You'll receive a JSON object like the one above, and you can access any of it's values using the @extra expression. For example, @extra.carrier.type will give you the value of the 'type' key and @extra.carrier.name will give you the name of the carrier. 

If you want your flow to evaluate the contact's carrier's type, you can add a 'Split by Expression' RuleSet like this one: 


The resulting flow might look something like this (landlines are exited): 

Considerations

  • Twilio does impose a small, pay-as-you-go fee for carrier and caller name lookups, more here. 
  • You can also pass basic auth credentials through the URL itself, e.g. https://ADa19ehc8fb23d2515:d09a32e56d8512685@lookups.twilio.com/v1/PhoneNumbers/@contact.tel_e164?Type=carrier


Questions? Comments? Let us know! We value your feedback.