Skip to contentSkip to navigationSkip to topbar
Rate this page:
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.Pilot : 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. Requires carrier approvals for certain countries. See full coverage details here.Public Beta : To request access, submit this form(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.General Access : 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 AccessPublic Beta: To request access, submit this form(link takes you to an external page).
Reassigned NumberAllows you to check if a phone number has been reassigned to a new user since a given date.US OnlyPublic Beta: 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:


_10
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.


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.


_10
curl -X GET \
_10
'https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}' \
_10
-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 Number

basic-lookup-for-a-valid-number page anchor

Valid E.164 phone number (free)

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v2.phoneNumbers('+14159929960')
_10
.fetch()
_10
.then(phone_number => console.log(phone_number.phoneNumber));

Output

_18
{
_18
"calling_country_code": "1",
_18
"country_code": "US",
_18
"phone_number": "+14159929960",
_18
"national_format": "(415) 992-9960",
_18
"valid": true,
_18
"validation_errors": null,
_18
"caller_name": null,
_18
"sim_swap": null,
_18
"call_forwarding": null,
_18
"line_status": null,
_18
"line_type_intelligence": null,
_18
"identity_match": null,
_18
"reassigned_number": null,
_18
"sms_pumping_risk": null,
_18
"phone_number_quality_score": null,
_18
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
_18
}

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.

Basic Lookup for an Invalid Number

basic-lookup-for-an-invalid-number page anchor

Invalid phone number that is too long (free)

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v2.phoneNumbers('+141599299600')
_10
.fetch()
_10
.then(phone_number => console.log(phone_number.nationalFormat));

Output

_20
{
_20
"calling_country_code": null,
_20
"country_code": null,
_20
"phone_number": "+141599299600",
_20
"national_format": null,
_20
"valid": false,
_20
"validation_errors": [
_20
"TOO_LONG"
_20
],
_20
"caller_name": null,
_20
"sim_swap": null,
_20
"call_forwarding": null,
_20
"line_status": null,
_20
"line_type_intelligence": null,
_20
"identity_match": null,
_20
"reassigned_number": null,
_20
"sms_pumping_risk": null,
_20
"phone_number_quality_score": null,
_20
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+141599299600"
_20
}

Lookup with data packages

lookup-with-data-packages page anchor

Comma separate multiple data packages

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v2.phoneNumbers('+447772000001')
_10
.fetch({fields: 'sim_swap,call_forwarding'})
_10
.then(phone_number => console.log(phone_number.valid));

Output

_31
{
_31
"calling_country_code": "44",
_31
"country_code": "GB",
_31
"phone_number": "+447772000001",
_31
"national_format": "07772 000001",
_31
"valid": true,
_31
"validation_errors": null,
_31
"caller_name": null,
_31
"sim_swap": {
_31
"last_sim_swap": {
_31
"last_sim_swap_date": "2020-11-05T20:52:09.322Z",
_31
"swapped_period": "PT24H",
_31
"swapped_in_period": true
_31
},
_31
"carrier_name": "Vodafone UK",
_31
"mobile_country_code": "276",
_31
"mobile_network_code": "02",
_31
"error_code": null
_31
},
_31
"call_forwarding": {
_31
"call_forwarding_status": true,
_31
"error_code": null
_31
},
_31
"line_status": null,
_31
"line_type_intelligence": null,
_31
"identity_match": null,
_31
"reassigned_number": null,
_31
"sms_pumping_risk": null,
_31
"phone_number_quality_score": null,
_31
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001"
_31
}

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)

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.

URI parameters
PhoneNumbertype: stringPII MTL: 30 days
Path Parameter

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


Fieldstype: stringNot PII
Query Parameter

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.


CountryCodetype: stringPII MTL: 30 days
Query Parameter

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


FirstNametype: stringNot PII
Query Parameter

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


LastNametype: stringNot PII
Query Parameter

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


AddressLine1type: stringNot PII
Query Parameter

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


AddressLine2type: stringNot PII
Query Parameter

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


Citytype: stringNot PII
Query Parameter

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


Statetype: stringNot PII
Query Parameter

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


PostalCodetype: stringNot PII
Query Parameter

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


AddressCountryCodetype: string<ISO COUNTRY CODE>Not PII
Query Parameter

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


NationalIdtype: stringNot PII
Query Parameter

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


DateOfBirthtype: stringNot PII
Query Parameter

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


LastVerifiedDatetype: stringNot PII
Query Parameter

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 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
calling_country_codetype: stringNot PII

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


phone_numbertype: string<PHONE NUMBER>PII MTL: 30 days

The phone number in E.164(link takes you to an external page) format, which consists of a + followed by the country code and subscriber number.


national_formattype: stringPII MTL: 30 days

validtype: booleanNot 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_errorstype: string[]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.

Possible values:
TOO_SHORTTOO_LONGINVALID_BUT_POSSIBLEINVALID_COUNTRY_CODEINVALID_LENGTHNOT_A_NUMBER

caller_nametype: objectPII MTL: 30 days

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


sim_swaptype: objectNot PII

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


call_forwardingtype: objectNot PII

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


line_statustype: objectNot PII

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


line_type_intelligencetype: objectNot PII

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


identity_matchtype: objectNot 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


reassigned_numbertype: objectNot PII

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_risktype: objectNot 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.


phone_number_quality_scoretype: objectNot PII

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


urltype: string<URI>Not PII

The absolute URL of the resource.


Rate this page: