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. See full coverage details here.General Access : 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.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

_19
{
_19
"calling_country_code": "1",
_19
"country_code": "US",
_19
"phone_number": "+14159929960",
_19
"national_format": "(415) 992-9960",
_19
"valid": true,
_19
"validation_errors": null,
_19
"caller_name": null,
_19
"sim_swap": null,
_19
"call_forwarding": null,
_19
"line_status": null,
_19
"line_type_intelligence": null,
_19
"identity_match": null,
_19
"reassigned_number": null,
_19
"sms_pumping_risk": null,
_19
"phone_number_quality_score": null,
_19
"pre_fill": null,
_19
"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.

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

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

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

_32
{
_32
"calling_country_code": "44",
_32
"country_code": "GB",
_32
"phone_number": "+447772000001",
_32
"national_format": "07772 000001",
_32
"valid": true,
_32
"validation_errors": null,
_32
"caller_name": null,
_32
"sim_swap": {
_32
"last_sim_swap": {
_32
"last_sim_swap_date": "2020-11-05T20:52:09.322Z",
_32
"swapped_period": "PT24H",
_32
"swapped_in_period": true
_32
},
_32
"carrier_name": "Vodafone UK",
_32
"mobile_country_code": "276",
_32
"mobile_network_code": "02",
_32
"error_code": null
_32
},
_32
"call_forwarding": {
_32
"call_forwarding_status": true,
_32
"error_code": null
_32
},
_32
"line_status": null,
_32
"line_type_intelligence": null,
_32
"identity_match": null,
_32
"reassigned_number": null,
_32
"sms_pumping_risk": null,
_32
"phone_number_quality_score": null,
_32
"pre_fill": null,
_32
"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.

PhoneNumberstringrequired
PII MTL: 30 days

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

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


CountryCodestring

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


FirstNamestring

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


LastNamestring

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


AddressLine1string

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


AddressLine2string

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


Citystring

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


Statestring

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


PostalCodestring

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


AddressCountryCodestring<iso-country-code>

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


NationalIdstring

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


DateOfBirthstring

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


LastVerifiedDatestring

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.


VerificationSidstring

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.

calling_country_codestring

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


phone_numberstring<phone-number>

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.


validboolean

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>]

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_nameobject

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


sim_swapobject

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


call_forwardingobject

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


line_statusobject

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


line_type_intelligenceobject

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


identity_matchobject

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_numberobject

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_riskobject

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_scoreobject

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


pre_fillobject

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>

The absolute URL of the resource.


Rate this page: