Skip to contentSkip to navigationSkip to topbar
On this page

Lookup v2 API


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

data-packages page anchor

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

PackageDescriptionCoverage & LimitationsRelease Stage and Access
Line Type IntelligenceGet 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 SwapGet 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(link takes you to an external page) to contact sales.
Call ForwardingGet 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(link takes you to an external page) to contact sales.
Line StatusGet 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(link takes you to an external page).
Identity MatchGet 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(link takes you to an external page).
Caller NameGet 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 ScoreAllows you to get a real-time risk assessment on a phone number's involvement in SMS pumping fraud.Worldwide AccessGenerally Available (GA): Available via self-service.
Reassigned NumberAllows you to check if a phone number has been reassigned to a new user since a given date.US OnlyGenerally Available (GA): To request access, submit this form(link takes you to an external page).

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)

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.


HTTP requests to the REST API are protected with HTTP Basic authentication(link takes you to an external page). 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.

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

You can find your Account SID and Auth Token in the Console(link takes you to an external page).

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


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.

Basic Lookup for a Valid NumberLink to code sample: Basic Lookup for a Valid Number
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchPhoneNumber() {
11
const phoneNumber = await client.lookups.v2
12
.phoneNumbers("+14159929960")
13
.fetch();
14
15
console.log(phoneNumber.phoneNumber);
16
}
17
18
fetchPhoneNumber();

Output

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/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchPhoneNumber() {
11
const phoneNumber = await client.lookups.v2
12
.phoneNumbers("+141599299600")
13
.fetch();
14
15
console.log(phoneNumber.nationalFormat);
16
}
17
18
fetchPhoneNumber();

Output

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/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchPhoneNumber() {
11
const phoneNumber = await client.lookups.v2
12
.phoneNumbers("+447772000001")
13
.fetch({ fields: "sim_swap,call_forwarding" });
14
15
console.log(phoneNumber.valid);
16
}
17
18
fetchPhoneNumber();

Output

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": true
14
},
15
"carrier_name": "Vodafone UK",
16
"mobile_country_code": "276",
17
"mobile_network_code": "02",
18
"error_code": null
19
},
20
"call_forwarding": {
21
"call_forwarding_status": true,
22
"error_code": null
23
},
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.

Query parameters

query-parameters page anchor

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.

(warning)

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.

Property nameTypeRequiredPIIDescription
PhoneNumberstringrequired
PII MTL: 30 days

The phone number to lookup in E.164 or national format. Default country code is +1 (North America).

Property nameTypeRequiredPIIDescription
FieldsstringOptional
Not PII

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.


CountryCodestringOptional

The country code(link takes you to an external page) used if the phone number provided is in national format.


FirstNamestringOptional

User’s first name. This query parameter is only used (optionally) for identity_match package requests.


LastNamestringOptional

User’s last name. This query parameter is only used (optionally) for identity_match package requests.


AddressLine1stringOptional

User’s first address line. This query parameter is only used (optionally) for identity_match package requests.


AddressLine2stringOptional

User’s second address line. This query parameter is only used (optionally) for identity_match package requests.


CitystringOptional

User’s city. This query parameter is only used (optionally) for identity_match package requests.


StatestringOptional

User’s country subdivision, such as state, province, or locality. This query parameter is only used (optionally) for identity_match package requests.


PostalCodestringOptional

User’s postal zip code. This query parameter is only used (optionally) for identity_match package requests.


AddressCountryCodestring<iso-country-code>Optional

User’s country, up to two characters. This query parameter is only used (optionally) for identity_match package requests.


NationalIdstringOptional

User’s national ID, such as SSN or Passport ID. This query parameter is only used (optionally) for identity_match package requests.


DateOfBirthstringOptional

User’s date of birth, in YYYYMMDD format. This query parameter is only used (optionally) for identity_match package requests.


LastVerifiedDatestringOptional

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.


VerificationSidstringOptional

The unique identifier associated with a verification process through verify API. This query parameter is only used (optionally) for pre_fill package requests.

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.

Property nameTypeRequiredDescriptionChild properties
calling_country_codestringOptional

International dialing prefix of the phone number defined in the E.164 standard.


country_codestringOptional

phone_numberstring<phone-number>Optional

The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.


national_formatstringOptional

validbooleanOptional

Boolean which indicates if the phone number is in a valid range that can be freely assigned by a carrier to a user.


validation_errorsarray[enum<string>]Optional

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.

Possible values:
TOO_SHORTTOO_LONGINVALID_BUT_POSSIBLEINVALID_COUNTRY_CODEINVALID_LENGTHNOT_A_NUMBER

caller_nameobjectOptional

An object that contains caller name information based on CNAM(link takes you to an external page).


sim_swapobjectOptional

An object that contains information on the last date the subscriber identity module (SIM) was changed for a mobile phone number.


call_forwardingobjectOptional

An object that contains information on the unconditional call forwarding status of mobile phone number.


line_statusobjectOptional

An object that contains line status information for a mobile phone number.


line_type_intelligenceobjectOptional

An object that contains line type information including the carrier name, mobile country code, and mobile network code.


identity_matchobjectOptional

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


reassigned_numberobjectOptional

An object that contains reassigned number information. Reassigned Numbers will return a phone number's reassignment status given a phone number and date


sms_pumping_riskobjectOptional

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.


phone_number_quality_scoreobjectOptional

An object that contains information of a mobile phone number quality score. Quality score will return a risk score about the phone number.


pre_fillobjectOptional

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.


urlstring<uri>Optional

The absolute URL of the resource.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.