Identifying Phone Number Carriers with Node.js and Twilio Lookup

Copy of Generic Blog Header 2 (2).png

Trolls and bad actors sometimes use phone numbers from free online providers to create fake profiles for making spam calls. Twilio's Lookup API helps you identify the carrier behind the phone number to learn which users have real mobile numbers.

Setting up

To lookup a phone number you will need:

Node.js and npm installed (do this first if you haven't already)
A free Twilio account
The Twilio Node library

To install the Twilio npm module, navigate to the directory where you want this code to live and navigate to the directory where you want this code to live and run the following command in your terminal to create a package for this project:

npm init --yes

The --yes argument just runs through all of the prompts that you would otherwise have to fill out or skip. Now that we have a package.json for our app, let’s install the Twilio module with the following shell command:

npm install twilio@3.33.0 --save

After this you should be good to write some code!

Looking up a carrier in JavaScript with Twilio

You can query the Twilio Lookup API for information about a phone number. There are two Types of requests the API can perform: carrier and caller-name. This example focuses on carrier.

All you need to do a carrier lookup in JavaScript is the following code:

// Set environment variables for your Account Sid and Auth Token!
// These can be found at twilio.com/console
const client = require('twilio')();

client.lookups.phoneNumbers('+18557477626')
  .fetch({ type: ['carrier'] })
  .then(phone_number => {
    console.log(phone_number.carrier) // All of the carrier info.
    console.log(phone_number.carrier.name) // Just the carrier name.
  });

Save that to a file called lookup.js.

Before running this code, make sure to grab your Account SID and Auth Token from your Twilio Console, and save them as environment variables named TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN, which the Twilio Node library will use when you run your code.

After setting these environment variables, run your code with your the following command:

node lookup.js

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

Try running the code again with your own phone number and see what comes back! Carriers rebrand themselves constantly and that the names used for carriers likely will change over time, so keep this in mind.

Are the carriers returned accurate?

Recent calls

Error message

Have you ever gotten a call from a weirdly invalid number or even from your own phone number? You might get a call from a weird 9-digit invalid number -- that can't be right! Given how current telephony systems are set up, 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?

We know we're not the only ones who are curious who's calling, so we built a public Twilio bot that uses the Lookup API to let you know a number's carrier.

Text +1 (855) 747-7626* with a phone number to check if it is from Twilio. That’s +1 (855) 747-ROBO

*standard text messaging rates may apply

If you're getting spam calls or texts from a Twilio number, this text hotline will help you report it. Learn more about this and what we're doing to stop spam on our platform.

Here are some other things you can build with the Lookup API:

And as always, Feel free to reach out and share your experiences or ask any questions.

Email: sagnew@twilio.com
Twitter: @Sagnewshreds
Github: Sagnew
Twitch (streaming live code): Sagnewshreds

Authors

Sam Agnew