SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Getting Started with the Twilio Lookup API

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.

This guide covers the following information:

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.

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:

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.

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.

Have more questions? Submit a request
Powered by Zendesk