Getting started with the Twilio lookup API – Twilio Support

Overview

This guide covers the basics of Twilio's lookup API and answers frequently asked questions about it.

What You Need To Know

Twilio's Lookup API allows users to query phone number information including number validation and formatting, carrier information, and other details associated with a phone number. Continue reading for an overview of the lookup API, how it works, and answers to frequently asked questions.

Frequently Asked Questions

How do I submit a lookup API request?

To Lookup a phone number, your application needs to make an HTTP GET request to Twilio’s Lookup REST API resource with the phone number you wish to look up. Here's a simple cURL request example:

curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/+13105555555" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

This example will do a lookup of the phone number (310) 555-5555 (3105555555)in line 1 of the code sample). It should return the following response:

{
"calling_country_code": "1",
"country_code": "US",
"phone_number": "+13105555555",
"national_format": "(310) 555-5555",
"valid": true,
"validation_errors": null,
"caller_name": null,
"sim_swap": null,
"call_forwarding": null,
"live_activity": null,
"line_type_intelligence": null,
"identity_match": null,
"reassigned_number": null,
"sms_pumping_risk": null,
"phone_number_quality_score": null,
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+13105555555"
}

This response indicates the phone number is valid, but not necessarily in service. The phone_number value is presented in E.164 format, which is required across Twilio’s Voice and Messaging APIs.

Notice: The Lookup v2 API will return "valid": false when the phone number is invalid. However, the Lookup v1 API will return an HTTP 404 status with a response containing "code": 20404 when a phone number is determined invalid. For full details, see the section How is phone number validity determined.

You can build on your basic Lookup request by adding data packages using the Fields query parameter. To add on data packages to your request, include the package names under the Fields parameter. For a full rundown of these optional parameters, see our Lookup API reference guide (Twilio Docs).

Where does Lookup data come from?

Lookup utilizes a variety of authoritative sources to return the most accurate response for a given Lookup type. We use direct connections to Mobile Network Operators, connections to various aggregators whom Twilio partners with, and databases managed by regional government agencies to obtain the data returned by the Lookup API. In many cases, Twilio will then apply proprietary logic and filtering on this data to maximize the value of the responses for the various use cases we support.

How is phone number validity determined?

Phone number validity is based on international phone numbering plan data administered by the ITU. Though the ITU should in theory have all global numbering plans on file, in practice, not every country will file their numbering plans with the ITU. Additionally, some government authorities may let telecom companies be responsible for administrating numbering plans. As a result of this lack of centralization, maintaining an accurate global numbering plan is a patchwork process. Twilio works with a variety of carrier partners to maintain accurate global numbering plan data but discrepancies can arise as numbering plans change and downstream providers must propagate these changes.

Lookup v1 will return an HTTP 404 status code if a phone number resource is invalid while Lookup v2 will return a "valid": true property

What are the Carrier Lookup 'Type' values?

Lookup v1

In the response for a Carrier Lookup, the type property specifies whether the phone is a landline, mobile, or voip phone.

Please note, since VoIP phone numbers are easier to obtain, they are sometimes used for fraudulent purposes. Customers often use Lookup to screen these numbers in their applications.

Lookup v2

In the response for a Line Type Intelligence Lookup, the type property specifies whether the phone is a landline, mobile, fixedVoip, nonFixedVoip personal, tollFree, premium, sharedCost, uan, voicemail, pager, or unknown.

The number screening using Lookup v2 can be even more meaningful due to the richness of types this version can return.

What about geographic support and limitations?

While the Lookup API is supported internationally, there are limitations to some request types:

Validation and Formatting Lookup: Number validation and formatting lookups are supported in all countries worldwide.

Caller Name Lookup: This is sourced by authoritative CNAM data, which is only supported by carriers in the US. CNAM lookups for phone numbers from other countries are not supported. For full details see Getting Started with CNAM Caller ID.

Carrier Lookup: This is supported worldwide.

For Lookup v1, please consider the following caveats:

The voip type will only be returned for carriers in the U.S. It is not supported outside of the U.S.
The mobile and landline types can be returned for all countries worldwide.
The mobile_country_code and mobile_network_code fields are returned in over 90 countries where mobile number portability is supported. For more information, see Why does the Mobile Country Code (MCC), Mobile Network Code (MNC) not show up for my phone number lookup?

For full worldwide support, please consider using Lookup v2 Line Type Intelligence.

Call Forwarding: Only numbers owned by major carriers in the United Kingdom are supported.

Identity Match: Check the list of supported countries in our coverage page. Keep in mind that some countries require pre-approval from mobile network operators prior to gaining access to this package.

Line Status: Generally supported worldwide.

Reassigned Number: This product is only available when querying US phone numbers.

SIM Swap: Check the list of supported countries in our coverage page.

SMS Pumping Risk: Generally supported worldwide.

Queries to Canada phone numbers for Carrier, Line Type Intelligence, SIM Swap and Live Activity require approval from the Canadian Local Number Portability Consortium. Refer to this article to learn more and request access. Without approval and access, queries to Canada numbers will return a 60601 error.

How do I process simultaneous lookup API requests?

The Lookup API only handles a phone number per request. For more information and recommendations, see Sending multiple requests to Twilio Lookup API.

Does Lookup cache response values?

We update our information with sufficient regularity to ensure it is up-to-date. The frequency of these updates depends on the type of data and the source of the data.

Conclusion

The Twilio Lookup API is a versatile tool that provides detailed information about phone numbers, including validation, formatting, and carrier details.