Lookup v2 API

BETA

This API version is currently available as a Beta release and is fully capable of supporting production workloads. Some features are publicly available via self-service, while some require carrier approvals and thus have gated access. Please see the table below for more details.

The Lookup v2 API allows you to query information on a phone number so that you can make a trusted interaction with your user. With this endpoint, you can format and validate phone numbers with the free Basic Lookup request and add on data packages to get even more in-depth carrier and caller information.

Using Lookup for the first time? Check out Lookup v2 Quickstart for step-by-step guidance.

Data packages

In Lookup v2, we offer the following optional paid data packages that you can add on to your request:

Package	Description	Coverage & Limitations	Release Stage and Access
Line Type Intelligence	Get the line type of a phone number including mobile, landline, fixed VoIP, non-fixed VoIP, toll-free, and more.	Worldwide support; Canada requires special approval.	Public Beta: Available via self-service.
SIM Swap	Get information on the last SIM change for a mobile phone number. See SIM Swap Overview for more information.	Countries in Europe, Latin America, and North America. See coverage.	Private Beta: Requires carrier approvals; please submit this form to contact sales.
Call Forwarding	Get the unconditional call forwarding status of a mobile phone number.	Only numbers owned by major carriers in the United Kingdom are supported.	Private Beta: Requires carrier approvals; please submit this form to contact sales.
Live Activity	Get the connectivity status, porting, and roaming information of a mobile phone number.	Worldwide support except for the US; Canada requires special approval. May not return data from every network.	Pilot: To request access, submit this form.
Identity Match	Get confirmation of ownership for a mobile phone number by comparing user-provided information against authoritative phone-based data sources.	Countries in Europe, Latin America, North America, and Australia. Requires carrier approvals for certain countries. See full coverage details here.	Pilot: To request access, submit this form.
Caller Name	Get information on the caller name and type for a mobile phone number.	Only numbers owned by carriers in the US are supported.	General Access: Available via self-service.

API base URL

All API URLs referenced in the documentation use the following base URL:

https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}

The Twilio REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

{PhoneNumber} is the phone number you are querying in E.164 or national format. If provided in national format, please also include the optional query parameter CountryCode in your request. If no country is provided, CountryCode will default to US.

Authentication

HTTP requests to the REST API are protected with HTTP Basic authentication. To learn more about how Twilio handles authentication, please refer to our security documentation.

You will use your Twilio Account SID as the username and your Auth Token as the password for HTTP Basic authentication.

curl -X GET \
'https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}' \
  -u '<YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>'

You can find your Account SID and Auth Token in the Console.

To learn more about authentication and interaction with the Twilio REST API, check out our documentation for requests and responses.

Regions support

To optimize application performance and control data residency, Lookup developers can select the Twilio Region that their request is processed out of. Twilio Lookup currently operates the following regions:

United States (US1) - default
Ireland (IE1)

Please see Using Lookup with Twilio Regions for more information.

Making a request

The Basic Lookup request is a free feature that returns the provided phone number in E.164 and national formats and performs basic phone number validation. To use Basic Lookup, send an HTTP GET request to the Lookup API Base URL.

Loading Code Sample...

Show sample response

Example JSON response

Show code

Valid E.164 phone number (free)

Basic Lookup for a Valid Number

Valid E.164 phone number (free)

Only valid numbers (for a given region, using length, and prefix information) will return Basic Lookup results. If you attempt to lookup a phone number which is invalid, you will receive ”valid”: false in the response. In some cases you will also receive a reason for the validation failure in the validation_errors field.

Loading Code Sample...

Show sample response

Example JSON response

Show code

Invalid phone number that is too long (free)

Basic Lookup for an Invalid Number

Invalid phone number that is too long (free)

Next, you can build on your Basic Lookup request by adding data packages using the Fields query parameter.

Query parameters

The following basic GET query string parameters allow you to specify the phone number you want information about, along with fields of additional data.

To add on data packages to your request, include the package names under the Fields parameter. The Basic Lookup formatting and validation data is also provided with every request by default.

Data packages are a paid feature.

When requesting data packages, you will incur charges on your account. Please double-check your code before running it so that you don't accidentally incur excessive unintended Lookup charges.

Parameters in REST API format
`phone_number` Path	get string PII MTL: 30 DAYS The phone number to lookup in E.164 or national format. Default country code is +1 (North America).
`fields` Optional	get string Not PII A comma-separated list of fields to return. Possible values are caller_name, sim_swap, call_forwarding, live_activity, line_type_intelligence, identity_match.
`country_code` Optional	get string PII MTL: 30 DAYS The country code used if the phone number provided is in national format.
`first_name` Optional	get string Not PII User’s first name. This query parameter is only used (optionally) for identity_match package requests.
`last_name` Optional	get string Not PII User’s last name. This query parameter is only used (optionally) for identity_match package requests.
`address_line_1` Optional	get string Not PII User’s first address line. This query parameter is only used (optionally) for identity_match package requests.
`address_line_2` Optional	get string Not PII User’s second address line. This query parameter is only used (optionally) for identity_match package requests.
`city` Optional	get string Not PII User’s city. This query parameter is only used (optionally) for identity_match package requests.
`state` Optional	get string Not PII User’s country subdivision, such as state, province, or locality. This query parameter is only used (optionally) for identity_match package requests.
`postal_code` Optional	get string Not PII User’s postal zip code. This query parameter is only used (optionally) for identity_match package requests.
`address_country_code` Optional	get iso_country_code Not PII User’s country, up to two characters. This query parameter is only used (optionally) for identity_match package requests.
`national_id` Optional	get string PII MTL: 30 DAYS User’s national ID, such as SSN or Passport ID. This query parameter is only used (optionally) for identity_match package requests.
`date_of_birth` Optional	get string PII MTL: 30 DAYS User’s date of birth, in YYYYMMDD format. This query parameter is only used (optionally) for identity_match package requests.

Response properties

The following properties are always returned. Note that some properties may be null unless that specific package was requested. For example, line_type_intelligence will be null unless the Line Type Intelligence package was requested.

Resource Properties in REST API format
`calling_country_code`	string Not PII International dialing prefix of the phone number defined in the E.164 standard.
`country_code`	string PII MTL: 30 DAYS The phone number's ISO country code.
`phone_number`	phone_number PII MTL: 30 DAYS The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.
`national_format`	string PII MTL: 30 DAYS The phone number in national format.
`valid`	boolean Not PII Boolean which indicates if the phone number is in a valid range that can be freely assigned by a carrier to a user.
`validation_errors`	enum:validation_error[] Not PII Contains reasons why a phone number is invalid. Possible values: TOO_SHORT, TOO_LONG, INVALID_BUT_POSSIBLE, INVALID_COUNTRY_CODE, INVALID_LENGTH, NOT_A_NUMBER.
`caller_name`	object PII MTL: 30 DAYS An object that contains caller name information based on CNAM.
`sim_swap`	object Not PII An object that contains information on the last date the subscriber identity module (SIM) was changed for a mobile phone number.
`call_forwarding`	object Not PII An object that contains information on the unconditional call forwarding status of mobile phone number.
`live_activity`	object Not PII An object that contains live activity information for a mobile phone number.
`line_type_intelligence`	object Not PII An object that contains line type information including the carrier name, mobile country code, and mobile network code.
`identity_match`	object Not PII An object that contains identity match information. The result of comparing user-provided information including name, address, date of birth, national ID, against authoritative phone-based data sources
`sms_pumping_risk`	object Not PII An object that contains information on if a phone number has been currently or previously blocked by Verify Fraud Guard for receiving malicious SMS pumping traffic as well as other signals associated with risky carriers and low conversion rates.
`url`	url Not PII The absolute URL of the resource.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Basic Lookup for a Valid Number

Basic Lookup for an Invalid Number

Need some help?

Thank you for your feedback!

Thanks for your feedback!