Twilio Lookup – An API to validate a phone number and reduce fraud

Lately, you had the pleasure of discovering some of Twilio’s services, in particular the Verify API which allows you to validate users, a great tutorial for sending SMS in Python, or the wonderful Authy double authentication application.

You really liked it, so today I suggest you discover Lookup by Twilio

What is Lookup?

Finally available in version 2, Lookup is a Twilio service that comes in the form of an API and allows those who integrate it into their projects to reduce the risk of fraud and spam. So how does it work?

Well when a user enters his phone number, Lookup API is able to determine if this number is valid by identifying the type of line (mobile, landline, VoIP, temporary number, etc.). For this, Lookup crosses the information given by the user with the information given by the telephone operators to check that they match. This makes it possible to avoid fraud such as SIM Swapping, the creation of false accounts, theft of accounts or spam, in particular by detecting the use of virtual numbers which are suspect by definition.

Beyond this very important security aspect, the fact of being able to validate a telephone number makes it possible to avoid errors in the distribution of messages or to pay for calls that will never succeed. And since this verification is done transparently without prompting the user with additional phone number validation, conversion rates increase, because there are fewer obstacles for the Internet user.

In its v1, Lookup only worked for numbers in the United States and Canada, but with this v2, Europe and the whole world are covered. Everything is obviously done in compliance with the GDPR and the personal data associated with the number cannot be retrieved via the API.

For this demo, I’ll show you how to embed Lookup in a Python script to do:

  • Simple number validation
  • Obtain the internationalized version of the number
  • Identify carrier and line type
  • Find out the name attached to a number

How to validate a phone number with Lookup?

I wrote my examples in Python, drawing inspiration from the official Twilio documentation, but be aware that with the libs available, you can obviously code this stuff in the language of your choice (Ruby, C#, PHP, Java…etc.)

Suppose you have a web page on which a user must enter his phone number. How to know if this number is valid at least for France and how to have it in its local version (06 12 13 14 15) and in its international version?

Well for that, you have to bring your Twilio API keys for V2 of Lookup and call the Lookup API like this:

from import Client


client = Client(account_sid, auth_token)

phone_number = client.lookups.v2.phone_numbers('0612131415').fetch(country_code="FR")

if phone_number.valid is True:
    print('Ce numéro est bien valide en France et sa version internationale est : ' + phone_number.phone_number)
    print('Ce numéro n'est pas valide en France')

A good way to check that the number sent to you is the right one. Moreover, to identify an error in a number, you can also use the “validation_errors” property like this, which will return one of these values ​​in the event of an error: TOO_SHORT, TOO_LONG, INVALID_BUT_POSSIBLE, INVALID_COUNTRY_CODE, INVALID_LENGTH, NOT_A_NUMBER.

from import Client


client = Client(account_sid, auth_token)

phone_number = client.lookups.v2.phone_numbers('+33451083391').fetch(


How to retrieve the different versions of a number?

Depending on the number entered, you may need either its country code, or the international number (country code + number), or its local version:

from import Client


client = Client(account_sid, auth_token)

phone_number = client.lookups.v2.phone_numbers(

print('Le code indicatif : ' + phone_number.calling_country_code)
print('Le code pays : ' + phone_number.country_code)
print('Le numéro au format national : ' + phone_number.national_format)
print('Le numéro au format international :  ' + phone_number.phone_number)

You will then get the following result:

Le code indicatif : 33
Le code pays : FR
Le numéro au format national : 06 12 13 14 15
Le numéro au format international :  +33612131415

Know how to identify the operator and the type of line linked to a telephone number?

A nice thing with Twilio’s lookup API is also the ability to identify the operator and line type associated with a number. Thus, you will know if it is a mobile, a fixed line, a VoIP number, etc.

To do this, we will use the “line_type_intelligence” property like this:

from import Client


client = Client(account_sid, auth_token)

phone_number = client.lookups.v2.phone_numbers(
    '0612131415').fetch(country_code="FR", fields="line_type_intelligence")

print('Opérateur téléphonique : ' + phone_number.line_type_intelligence["carrier_name"])
print('Type de ligne : ' + phone_number.line_type_intelligence["type"])

And here is the type of return you will get:

Opérateur téléphonique : ORANGE FRANCE (01)
Type de ligne : mobile

Other paid features or still in beta, also allow you to do very useful things such as the possibility of knowing if the SIM card has been swapped recently (to avoid scams) or quite simply to find the name linked to the telephone number. But these options are not available in all countries. I invite you to consult this page for the simswap.

How do I find out who owns a number?

This possibility does not work for France (Because GDPR), but only for certain countries such as the United States or Great Britain and only for certain numbers. Take for example this US number. By using the “caller_name” property, it is possible to know what the name linked to this number is and whether it is a business number or not.

from import Client


client = Client(account_sid, auth_token)

phone_number = client.lookups.v2.phone_numbers(

print("Nom : " + phone_number.caller_name["caller_name"])
print("Type de numéro : " +phone_number.caller_name["caller_type"])

Here is what I get, namely the name of a plumbing company located in New York.

Type de numéro : BUSINESS

As you will have understood, integrating Lookup v2 into your applications is quite simple to implement and costs very little. This makes it possible to ensure that the telephone details entered by a user are correct and that it is not a false number or a number which is the subject of fraud, in particular in the context of a SIM swapping.

You will also eliminate number validation operations that are quite painful for the user, which will allow you to increase your conversion rates and above all reduce your costs of sending messages in the event of an invalid number. In short, a must for all projects that require proper user phone number validation.

5/5 - (1 vote)
SAKHRI Mohamed
SAKHRI Mohamed

The blog of a computer enthusiast who shares news, tutorials, tips, online tools and software for Windows, macOS, Linux, Web designer and Video games.

Articles: 3764

Leave a Reply

Your email address will not be published.