Lookup v2 API
Twilio Lookup provides powerful, real-time phone number intelligence to help businesses verify users and prevent fraud by ensuring accurate information about phone number type, carrier, country, if the phone number is active or reachable, phone number ownership, if contact consent is still valid, whether the phone number has been attributed to a new SIM, and more without disrupting the user experience. This solution enhances user authentication and reduces costs by improving SMS and call delivery with precise phone number validation.
The Lookup 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.
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. |
| Line Status | Get the status information of a mobile phone number. | 140+ countries and may not return data from every network. | Private Beta : 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. See full coverage details here. | Generally Available : Certain countries require carrier approval to start the process. Submit this form to request access. |
| 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. | Generally Available : Available via self-service. |
| SMS Pumping Risk Score | Allows you to get a real-time risk assessment on a phone number's involvement in SMS pumping fraud. | Worldwide Access | Generally Available (GA): Available via self-service. |
| Reassigned Number | Allows you to check if a phone number has been reassigned to a new user since a given date. | US Only | Generally Available (GA): To request access, submit this form. |
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.
Warning
In some cases, non-US phone numbers in national format with no + sign or CountryCode query parameter are being processed as valid. This is not changing in V1 in the future but it is an unintended behavior and could lead to ambiguous validation responses.
To authenticate requests to the Twilio APIs, Twilio supports HTTP Basic authentication. Use your API key as the username and your API key secret as the password. You can create an API key either in the Twilio Console or using the API.
Note: Twilio recommends using API keys for authentication in production apps. For local testing, you can use your Account SID as the username and your Auth token as the password. You can find your Account SID and Auth Token in the Twilio Console.
Learn more about Twilio API authentication.
1curl -X GET https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber} \2-u $TWILIO_API_KEY:$TWILIO_API_KEY_SECRET
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.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchPhoneNumber() {11const phoneNumber = await client.lookups.v212.phoneNumbers("+14159929960")13.fetch();1415console.log(phoneNumber.phoneNumber);16}1718fetchPhoneNumber();
Response
Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.1{2"calling_country_code": "1",3"country_code": "US",4"phone_number": "+14159929960",5"national_format": "(415) 992-9960",6"valid": true,7"validation_errors": null,8"caller_name": null,9"sim_swap": null,10"call_forwarding": null,11"line_status": null,12"line_type_intelligence": null,13"identity_match": null,14"reassigned_number": null,15"sms_pumping_risk": null,16"phone_number_quality_score": null,17"pre_fill": null,18"url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"19}
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchPhoneNumber() {11const phoneNumber = await client.lookups.v212.phoneNumbers("+141599299600")13.fetch();1415console.log(phoneNumber.nationalFormat);16}1718fetchPhoneNumber();
Response
Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.1{2"calling_country_code": null,3"country_code": null,4"phone_number": "+141599299600",5"national_format": null,6"valid": false,7"validation_errors": [8"TOO_LONG"9],10"caller_name": null,11"sim_swap": null,12"call_forwarding": null,13"line_status": null,14"line_type_intelligence": null,15"identity_match": null,16"reassigned_number": null,17"sms_pumping_risk": null,18"phone_number_quality_score": null,19"pre_fill": null,20"url": "https://lookups.twilio.com/v2/PhoneNumbers/+141599299600"21}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchPhoneNumber() {11const phoneNumber = await client.lookups.v212.phoneNumbers("+447772000001")13.fetch({ fields: "sim_swap,call_forwarding" });1415console.log(phoneNumber.valid);16}1718fetchPhoneNumber();
Response
Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.1{2"calling_country_code": "44",3"country_code": "GB",4"phone_number": "+447772000001",5"national_format": "07772 000001",6"valid": true,7"validation_errors": null,8"caller_name": null,9"sim_swap": {10"last_sim_swap": {11"last_sim_swap_date": "2020-11-05T20:52:09.322Z",12"swapped_period": "PT24H",13"swapped_in_period": true14},15"carrier_name": "Vodafone UK",16"mobile_country_code": "276",17"mobile_network_code": "02",18"error_code": null19},20"call_forwarding": {21"call_forwarding_status": true,22"error_code": null23},24"line_status": null,25"line_type_intelligence": null,26"identity_match": null,27"reassigned_number": null,28"sms_pumping_risk": null,29"phone_number_quality_score": null,30"pre_fill": null,31"url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001"32}
Next, you can build on your Basic Lookup request by adding data packages using the Fields query parameter.
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.
The phone number to lookup in E.164 or national format. Default country code is +1 (North America).
A comma-separated list of fields to return. Possible values are validation, caller_name, sim_swap, call_forwarding, line_status, line_type_intelligence, identity_match, reassigned_number, sms_pumping_risk, phone_number_quality_score, pre_fill.
The country code used if the phone number provided is in national format.
User’s first name. This query parameter is only used (optionally) for identity_match package requests.
User’s last name. This query parameter is only used (optionally) for identity_match package requests.
User’s first address line. This query parameter is only used (optionally) for identity_match package requests.
User’s second address line. This query parameter is only used (optionally) for identity_match package requests.
User’s city. This query parameter is only used (optionally) for identity_match package requests.
User’s country subdivision, such as state, province, or locality. This query parameter is only used (optionally) for identity_match package requests.
User’s postal zip code. This query parameter is only used (optionally) for identity_match package requests.
User’s country, up to two characters. This query parameter is only used (optionally) for identity_match package requests.
User’s national ID, such as SSN or Passport ID. This query parameter is only used (optionally) for identity_match package requests.
User’s date of birth, in YYYYMMDD format. This query parameter is only used (optionally) for identity_match package requests.
The date you obtained consent to call or text the end-user of the phone number or a date on which you are reasonably certain that the end-user could still be reached at that number. This query parameter is only used (optionally) for reassigned_number package requests.
The unique identifier associated with a verification process through verify API. This query parameter is only used (optionally) for pre_fill package requests.
The optional partnerSubId parameter to provide context for your sub-accounts, tenantIDs, sender IDs or other segmentation, enhancing the accuracy of the risk analysis.
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.
International dialing prefix of the phone number defined in the E.164 standard.
The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.
Boolean which indicates if the phone number is in a valid range that can be freely assigned by a carrier to a user.
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.
TOO_SHORTTOO_LONGINVALID_BUT_POSSIBLEINVALID_COUNTRY_CODEINVALID_LENGTHNOT_A_NUMBERAn object that contains caller name information based on CNAM.
An object that contains information on the last date the subscriber identity module (SIM) was changed for a mobile phone number.
An object that contains information on the unconditional call forwarding status of mobile phone number.
An object that contains line status information for a mobile phone number.
An object that contains line type information including the carrier name, mobile country code, and mobile network code.
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
An object that contains reassigned number information. Reassigned Numbers will return a phone number's reassignment status given a phone number and date
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.
An object that contains information of a mobile phone number quality score. Quality score will return a risk score about the phone number.
An object that contains pre fill information. pre_fill will return PII information associated with the phone number like first name, last name, address line, country code, state and postal code.
The absolute URL of the resource.