A2P 10DLC Campaign Vetting Delays: Twilio cannot approve 10DLC Campaigns ourselves, and must rely on third parties who control our connections to carriers to sign off. These external processes are creating several week delays for our customers. We continue to escalate these issues and are working to reduce delays wherever possible. Further details will be shared in the Campaign Vetting Changes article as they become available.

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 the caller name 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 lookup. Here's a simple cURL request example:

curl -X GET 'https://lookups.twilio.com/v1/PhoneNumbers/3105555555' \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

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

{
  "caller_name": null,
  "country_code": "US",
  "phone_number": "+13105555555",
  "national_format": "(310) 555-5555",
  "carrier": null,
  "add_ons": null,
  "url": "https://lookups.twilio.com/v1/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 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.

The Lookup API supports additional parameters to specify a Carrier Lookup (Type=carrier), a Caller ID Lookup (Type=caller-name), and more. 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 and non-authoritative sources to return the most accurate response for a given Lookup type. See more details on each Lookup type below:

Lookup type Data sources Update frequency
Number validation and formatting International numbering plan data Bi-weekly
Carrier Mobile number portability and numbering plan data from each country’s phone number regulator (where available). Varies by country
(At minimum every 30 min, at maximum every 24 hrs)
Caller Name Network CNAM data supplied by carriers for the phone numbers that they own. Varies by network

How is phone number validity determined?

Lookup will return an HTTP 404 status code if a phone number resource is invalid. 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.

What are the Carrier Lookup 'Type' values?

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

  • landline (aka 'fixed' or 'wireline') and mobile (aka 'non-fixed' or 'wireless') are service type designations provided by the carrier who owns the number.
  • voip is a classification on the carrier.

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.

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 with 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?
  • Queries to Canada phone numbers 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?

To improve performance of the service, Lookup may cache response values for Caller Name and Carrier Lookups for up to one hour. Validation and formatting lookups are not cached.

Have more questions? Submit a request
We can’t wait to see what you build.
Powered by Zendesk