Lookup v1 Quickstart

Lookup allows you to systematically ascertain information about phone numbers. With Lookup, you can identify local-friendly number formats and reduce the likelihood of undelivered messages.

First, decide what you'd like to know about your numbers. Format lookups are free and allow you to identify and adjust international phone numbers into E.164 format for optimal message deliverability. Carrier lookups cost $0.005 per lookup and allow you to identify both the phone type (mobile, landline or VoIP) and the carrier behind the phone number.

Let's look at the details:

• First log into your Twilio Account. On the Dashboard there is a section labeled "API Credentials". There you will find your Account SID and Auth Token. You'll need these to authenticate your request.
• To perform a Lookup, we'll be making a HTTP GET request to the lookup subdomain. lookups.twilio.com/v1/PhoneNumbers/{PhoneNumber}
• We will need to include the phone number we want to look up.
• We may then specify any additional information as GET parameters.

Let's try this out by using curl to make the following request in our terminal:

1
curl -XGET "https://lookups.twilio.com/v1/PhoneNumbers/5108675309?CountryCode=US&Type=carrier" \
2
    -u '{AccountSid}:{AuthToken}'

Now we want to integrate Lookup with our application. Let's try it out with our helper library.

You may want to use Format Lookup in order to reformat international numbers given to you by your customers in local format. In this case, you need to specify the number and the country you believe the phone number is from. Note that this lookup is free.

The Twilio helper libraries assist with this. Open a new file and add the following lines:

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.v1
12
    .phoneNumbers("+15108675310")
13
    .fetch({ countryCode: "US" });
14

15
  console.log(phoneNumber.callerName);
16
}
17

18
fetchPhoneNumber();

1
{
2
  "caller_name": null,
3
  "carrier": null,
4
  "add_ons": null,
5
  "country_code": "US",
6
  "national_format": "(510) 867-5310",
7
  "phone_number": "+15108675310",
8
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310"
9
}

You'll want to include the country code of the phone number that you would like formatted. If not included, the country code will default to the US.

You may also want to do a lookup to determine the phone number type and carrier for your phone number. Note that this costs $0.005 per lookup.

To do this lookup, you'll want to include the carrier parameter. Similar to the code above, we can make this request with the following snippet:

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.v1
12
    .phoneNumbers("(510)867-5310")
13
    .fetch({
14
      countryCode: "US",
15
      type: ["carrier"],
16
    });
17

18
  console.log(phoneNumber.carrier);
19
}
20

21
fetchPhoneNumber();

1
{
2
  "caller_name": null,
3
  "carrier": {
4
    "error_code": null,
5
    "mobile_country_code": "310",
6
    "mobile_network_code": "456",
7
    "name": "verizon",
8
    "type": "mobile"
9
  },
10
  "country_code": "US",
11
  "national_format": "(510) 867-5310",
12
  "phone_number": "(510)867-5310",
13
  "add_ons": null,
14
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310"
15
}

Now you're ready to look up your customers' phone numbers and reach them in the most appropriate ways!