How to Lookup a phone number with the Twilio CLI

August 06, 2019
Written by

Lookup a phone number with the Twilio CLI

Some bad actors use phone numbers from free online providers to create fake profiles to scam or spam. Twilio's Lookup API helps you identify the carrier behind the phone number to learn which users have real mobile numbers. And you can use it with the new Twilio CLI!

Lookup a carrier with the Twilio CLI

To lookup a phone number with the Twilio CLI you will need:

Follow instructions to install the Twilio CLI then in your terminal log in with your account credentials found in the console:

twilio login

You can query the Twilio Lookup API for information about a phone number. There are two Types  of requests the API can perform:

  1. Carrier - includes line type (i.e. mobile, landline, voip) and telecom provider (i.e. Verizon, Level 3 Communications, Twilio)
  2. Caller name - includes caller identification information when available (US only)

The following request will return carrier information about a phone number. The phone number in the request URL must be in E.164 format like +18557477626.

In your terminal, run the following code:

twilio api:lookups:v1:phone-numbers:fetch --phone-number +18557477626 --type carrier -o json

If you want to add this functionality in an application, Twilio has helper libraries in languages including C#, Ruby, Python, Java, JavaScript, and PHP. This will return a JSON response:

  {
    "addOns": null

You can see that the carrier name for our example number, 1 (855) 747-7626, is Twilio and the line type is voip. Similar information is returned for mobile and landline carriers such as AT&T or Level 3 Communications.

Try running the request again with your own phone number and see what comes back! Bear in mind that carriers rebrand themselves constantly and that the names used for carriers likely will change over time.

Are the carriers returned accurate?

recent calls with an invalid number

Have you ever gotten a call from a weirdly invalid number or even from your own phone number? I got a call from this 9-digit invalid number earlier today -- that can't be right! The way telephony systems are set up today, anyone can spoof a call or a text from any number. Even if they don’t own that number.

Twilio doesn't allow customers to use numbers that they don't own. This practice, unfortunately, doesn’t prevent others from spoofing Twilio serviced numbers. This isn't cool so we're working with other industry leaders to address spoofing. Although we’re optimistic these efforts will have a big impact, we don’t expect them to start paying off until 2020.

After looking up carrier information, what's next?

Lookup has a wide variety of use cases including spam filtering, database clean up, caller identification and more. Here are some other things you can build with the Lookup API:

The Twilio CLI is open source and on GitHub. Check out the CLI documentation for more ideas and resources.