Build an allow list to filter sign ups by country with Twilio Lookup

Time to read: 2 minutes

June 17, 2021
Written by
Kelley Robinson
Twilion
Reviewed by
Mingchao Ma
Twilion
Matthew Gilliard
Twilion
Miguel Grinberg
Twilion

Build an allow list to filter sign ups by country with Twilio Lookup

If you're using the Verify API for sign up and worried about SMS pumping, we recommend enabling Fraud Guard and geo-permissions. To manage enabled and blocked countries, visit the Verify section of the Twilio Console.

This post offers a code-based approach to filtering traffic using the Lookup API. This approach will work well if you need to dynamically update the allow list or need additional logic around your sign up flow.

Using an allow list of countries at sign-up is a great way to ensure you're meeting compliance requirements, reducing fraud, or otherwise controlling your onboarding pipeline. The Twilio Lookup API provides a set of tools for validating phone numbers and conveniently includes the country code in the response so you can easily build an allow list.

Here's a quick JavaScript snippet of an example allow list:

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require("twilio")(accountSid, authToken);

// hard coded for demo purposes only
const allow = ["US", "CA", "MX"];

client.lookups.v2
 .phoneNumbers("+15108675310")
 .fetch()
 .then((resp) => {
   if (allow.includes(resp.countryCode)) {
     console.log("allowed!");
   } else {
     console.log("denied");
   }
 });

The rest of the post will cover building this solution with the Twilio Lookup API and Node.js. The Twilio Lookup API supports multiple languages though, so check out the docs for examples in the language of your preference.

Prerequisites for building a country code allow list

To code along with this post you'll need to:

Step 1: Sign up for or sign into your Twilio account

Step 2: Install Node JS https://nodejs.org/en/download

Step 3: Install Twilio CLI (learn more)

npm install -g twilio-cli

Step 3: Install the Serverless CLI plugin

twilio plugins:install @twilio-labs/plugin-serverless

Step 4: Login to the CLI with your Twilio account credentials

twilio login

Download the Lookup starter template

Using the CLI, clone the international telephone input template from the Twilio code exchange:

twilio serverless:init lookup-allow-list --template=international-telephone-input && cd lookup-allow-list

Open up the .env file and make sure your Twilio Account Credentials (ACCOUNT_SID and AUTH_TOKEN) have been populated. You can start the app by running:

twilio serverless:start

Open http://localhost:3000/index.html in a browser; you should be able to input your phone number and see it in E.164 format:

Phone number input field with a verify button and a success message that says "Phone number in E.164 format: +15108675310"

Right now the application does a really handy thing by accepting international formatted numbers and converting them to the standard E.164 format. The Lookup API then validates whether the number is valid or not. If you try inputting just 12345 or any other invalid phone number you'll get an error.

Add an allow list to your sign-up form

Avoid hard-coding these values in a production environment. We recommend loading the list from external storage like a configuration file or database so that it is easier to update the list without changing the code itself.

To add an allow list, open up the functions/lookup.js file and add the following line after const client = …:

const allow = ["US", "CA", "MX"]

This list is using ISO 3166-2 Alpha-2 country codes, which the Lookup API also uses. In our example, the United States, Canada, and Mexico are the allowed countries.

If you look at the rest of the function, you might notice that we're not actually using the response from the Lookup API. To make use of the response and grab the country code that's returned, replace the 5 line block of code that starts with response.setStatusCode(200); with:

if (allow.includes(resp.countryCode)) {
 response.setStatusCode(200);
 response.setBody({
   success: true,
 });
 // continue
 return callback(null, response);
} else {
 response.setStatusCode(401);
 response.setBody({
   success: false,
   error: "Country code not allowed",
 });
 // throw an error
 return callback(null, response);
}

Finally, head over to assets/index.html and update line 73 to report the function's error message:

error.innerHTML = json.error;

Make sure the project is running with twilio serverless:start, head over to http://localhost:3000/index.html and test it out! A US number like 5108675310 will work, but if you select the German flag from the drop down and input an otherwise valid German number like 015123456789 you should see the error message "Country code not allowed."

Here's a link to the completed code on my GitHub.

Other uses for the Lookup API

You could use the reverse logic and use Lookup to block specific countries if you know you aren't expecting traffic from those places.

Lookup can also be used to detect line type, carrier, sim swaps, or live activity and could be used in a similar way to only allow mobile numbers or block a specific carrier.

Of course, once you've implemented Lookup you'll want to Verify phone numbers using Twilio's Verify API. Here are some more resources for account security that you might enjoy:

I can't wait to see what you build and secure with Twilio!

 

 

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.