Back to Blog
Language How-Tos

How to Look Up a Phone Number Carrier and Type in Twilio Using Node.js

Use the Twilio Lookup API in Node.js to check number type, carrier, and validity before sending messages or making calls.

DA
Danial A
Senior Twilio Consultant, Telphi Consulting
June 22, 2026
8 min read
Twilio
Node.js
JavaScript
How-To
Code
How to Look Up a Phone Number Carrier and Type in Twilio Using Node.js

This tutorial uses the Twilio Lookup API in Node.js to validate phone numbers, determine their line type (mobile, landline, or VoIP), and retrieve carrier information before sending messages or making calls. It targets developers who want to pre-filter recipient lists to avoid wasting SMS spend on landlines that cannot receive text messages. You will query the Lookup v2 API with a single number, inspect the line type intelligence fields, and make a routing decision based on the result.

Prerequisites and Setup

Install the Twilio SDK with npm install twilio dotenv and configure your Account SID and Auth Token in a .env file. The Lookup API charges a small per-request fee, so cache results in a database with a TTL rather than calling the API on every page load or send. The Lookup v2 endpoint is accessed through client.lookups.v2.phoneNumbers(number).fetch(), where number is the E.164 formatted phone number you want to check. Pass the fields option set to 'line_type_intelligence' to include carrier and line type data in the response; without this option the API only returns basic validity information.

npm install twilio dotenv

# .env
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here

The Complete Code

The fetch call returns a result object whose lineTypeIntelligence property is a nested object containing a type key with values like 'mobile', 'landline', 'voip', or 'nonFixedVoip'. The valid boolean at the top level of the result indicates whether the number exists and is properly formatted before you check the line type. Catching errors and checking for a 404 status lets you handle completely invalid numbers gracefully without crashing. The function returns a plain object with the relevant fields so the calling code is not tightly coupled to the Twilio SDK's response structure.

require('dotenv').config();
const twilio = require('twilio');

const client = twilio(
  process.env.TWILIO_ACCOUNT_SID,
  process.env.TWILIO_AUTH_TOKEN
);

async function lookupNumber(phoneNumber) {
  try {
    const result = await client.lookups.v2
      .phoneNumbers(phoneNumber)
      .fetch({ fields: 'line_type_intelligence' });

    const lti = result.lineTypeIntelligence || {};
    return {
      valid:       result.valid,
      phoneNumber: result.phoneNumber,
      countryCode: result.countryCode,
      lineType:    lti.type,
      carrier:     lti.carrierName,
    };
  } catch (err) {
    return { valid: false, error: err.message };
  }
}

async function main() {
  const info = await lookupNumber('+15551234567');
  console.log(info);

  if (info.valid && info.lineType === 'mobile') {
    console.log('Safe to send SMS to this number.');
  } else {
    console.log('Skipping: not a mobile number.');
  }
}

main();

Testing and Debugging

Test with a known mobile number, a landline, and a VoIP number such as a Google Voice number to verify the lineType field returns different values for each category. If lineTypeIntelligence is null in the response, you likely omitted the fields parameter in the fetch call; add it and retry. A thrown error with status 404 means the number format is invalid or the number does not exist; validate E.164 format locally with a regex before calling the API to catch obvious mistakes cheaply. Monitor your Twilio account usage to ensure lookup volume stays within your budget, especially if you are validating large contact lists.

Taking It Further

Build a pre-send filter function that accepts an array of numbers, runs lookups in parallel using Promise.allSettled(), and returns separate arrays of mobile and non-mobile numbers for different downstream actions. Add CNAM lookup by including 'caller_name' in the fields string to retrieve the registered caller name associated with the number. Cache lookup results in Redis keyed by phone number with a 7-day TTL, since carrier assignments change infrequently, to dramatically reduce per-lookup API costs for repeat numbers. Combine lookup with the Verify API to build a registration flow that rejects non-mobile numbers with a clear user-facing error before sending an OTP.

Contact Telphi Consulting to build smart number validation pipelines that improve deliverability and reduce messaging costs in Node.js.

Share this article:
0 views

Ready to Transform Your Business Communications?

Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.

Comments (0)

Join the discussion and share your thoughts (AI-moderated for quality)

Protected by AI moderation

Be the first to comment

No comments yet. Share your thoughts below.