Skip to contentSkip to navigationSkip to topbar
On this page

Lookup v2 Quickstart


The Lookup API allows you to query information on a phone number so that you can make a trusted interaction with your user. With Lookup, you can format and validate phone numbers with the free Basic Lookup request to increase deliverability and get detailed information on a number's carrier and caller by adding on optional data packages. See Lookup v2 API Reference for more details on Lookup's capabilities.

In this Quickstart we will explore how to get started with Lookup and learn how to make these requests:


Setup: Authentication

setup-authentication page anchor

New to Twilio? You'll want to start by creating a Twilio Account(link takes you to an external page).

Next, login to Twilio Console(link takes you to an external page) and note your Account SID and Auth Token. You'll need these to authenticate your Lookup requests with HTTP Basic authentication(link takes you to an external page), using your Account SID as the username and your Auth Token as the password.


All Lookup requests begin with an HTTP GET request to this 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 only required parameter and represents the phone number you are querying in E.164 or national format. If the phone number is provided in national format, please also specify the country in the optional parameter CountryCode. Otherwise, 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.


A Basic Lookup returns the provided phone number in E.164 and national formats and validates the phone number. Note that this is a free feature.

Let's try it out by making this cURL request in our terminal, replacing the PhoneNumber, YOUR_ACCOUNT_SID, and YOUR_AUTH_TOKEN variables with your own data:

1
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}" \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

You should see a response similar to this one:

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
"live_activity": null,
12
"line_type_intelligence": null,
13
"identity_match": null,
14
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
15
}

The fields calling_country_code, country_code, phone_number, and national_format provide formatting information and the valid field indicates if the phone number could be a valid assigned number.

See this example below for how you can use a Twilio Helper Library in your preferred language to perform the same request.

Basic LookupLink to code sample: Basic Lookup
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
}

Introducing Lookup's data packages

introducing-lookups-data-packages page anchor

Lookup supports a number of data packages that allow you to query for additional carrier and caller information relating to a phone number. See Lookup v2 API Reference for a full list of available packages and how to onboard to each one.

In this Quickstart, we'll explain how to use the Line Type Intelligence package.

Perform a Line Type Intelligence Lookup

perform-a-line-type-intelligence-lookup page anchor

The Line Type Intelligence package allows you to get the line type of a phone number including mobile, landline, fixed VoIP, non-fixed VoIP, toll-free, and more. Note that this is a paid feature.

The video below shows how to check a phone number's line type with Lookup using Node.js and the Twilio Node Helper Library.

To make a Line Type Intelligence request, build on the API base URL by adding the Fields parameter with the value line_type_intelligence.

Make the following cURL request in the terminal, replacing the PhoneNumber, YOUR_ACCOUNT_SID, and YOUR_AUTH_TOKEN variables with your own data:

1
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}?Fields=line_type_intelligence" \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Let's check the response:

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
"live_activity": null,
12
"line_type_intelligence":
13
{
14
"error_code": null,
15
"mobile_country_code": "240",
16
"mobile_network_code": "38",
17
"carrier_name": "Twilio - SMS/MMS-SVR",
18
"type": "nonFixedVoip"
19
},
20
"identity_match": null,
21
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
22
}

All of the fields we saw in the previous Basic Lookup request are present along with new information included in the line_type_intelligence object.

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({ fields: "line_type_intelligence" });
14
15
console.log(phoneNumber.lineTypeIntelligence);
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": {
13
"error_code": null,
14
"mobile_country_code": "240",
15
"mobile_network_code": "38",
16
"carrier_name": "Twilio - SMS/MMS-SVR",
17
"type": "nonFixedVoip"
18
},
19
"identity_match": null,
20
"reassigned_number": null,
21
"sms_pumping_risk": null,
22
"phone_number_quality_score": null,
23
"pre_fill": null,
24
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
25
}

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.