Twilio Lookup API — Complete Guide to Phone Number Intelligence

In this tutorial, you will learn about Twilio Lookup API. We cover key concepts, practical examples, and best practices to help you master this topic.

Twilio Lookup API provides phone number intelligence including carrier information, line type, caller name, and number formatting without making a call or sending a message to the number.

What You'll Learn

• Looking up carrier and line type information
• Validating and formatting phone numbers
• Getting caller name and SIM card data

Why It Matters

Without Lookup API, identifying whether a number is mobile or landline, or getting carrier information, requires external databases or trial calls. Lookup provides this instantly with a single API call.

Real-World Use

Durga Antivirus Pro account verification uses Twilio Lookup to validate phone numbers during registration. If a number is identified as a VoIP or landline when mobile is required, the user is prompted for a different number.

flowchart LR
    I["Phone Number Input"] --> L["Twilio Lookup"]
    L --> V["Validate Format"]
    L --> C["Carrier Info"]
    L --> T["Line Type"]
    L --> N["Caller Name"]
    T --> M["Mobile?"]
    M -->|"Yes"| S["Send SMS"]
    M -->|"No"| P["Prompt User"]
    style L fill:#dbeafe,stroke:#2563eb

Code Examples

from twilio.rest import Client

client = Client(account_sid, auth_token)

# Basic phone number lookup
number = client.lookups.v1.phone_numbers('+15551234567').fetch(
    type=['carrier', 'caller-name']
)

print(f"Country: {number.country_code}")
print(f"National Format: {number.national_format}")
print(f"Carrier: {number.carrier['name']}")
print(f"Line Type: {number.carrier['type']}")
print(f"Caller Name: {number.caller_name['caller_name']}")

Expected output: Lookup returns country, formatted number, carrier name, line type (mobile/landline/VoIP), and caller name.

const twilio = require('twilio');
const client = new twilio(accountSid, authToken);

async function lookupNumber(phone) {
  try {
    const response = await client.lookups.v1
      .phoneNumbers(phone)
      .fetch({ type: ['carrier', 'caller-name'] });

    console.log({
      phoneNumber: response.phoneNumber,
      countryCode: response.countryCode,
      carrier: response.carrier.name,
      lineType: response.carrier.type,
      callerName: response.callerName?.callerName,
    });
  } catch (err) {
    if (err.status === 404) {
      console.log('Invalid phone number');
    } else {
      console.error('Lookup failed:', err);
    }
  }
}

lookupNumber('+15551234567');

Expected output: JSON object with carrier info and line type; 404 for invalid numbers.

# Validate and format numbers in bulk
from twilio.rest import Client

client = Client(account_sid, auth_token)

phone_numbers = [
    '+14155551234',
    '+442071234567',
    '+12125559876',
]

for number in phone_numbers:
    try:
        result = client.lookups.v1.phone_numbers(number).fetch()
        print(f"{number} -> {result.country_code} {result.national_format} ({result.carrier['type']})")
    except Exception as e:
        print(f"{number} -> Invalid: {e}")

Expected output: Each phone number validated and displayed with country, national format, and line type.

Common Mistakes

1. Not Caching Lookup Results

Each lookup costs money. Cache results for numbers you have already looked up to avoid repeated charges.

2. Ignoring the 404 Response

Lookup returns 404 for invalid numbers. Always check for 404 before processing the result.

3. Assuming Line Type Availability

Line type is not available for all countries or carriers. Handle missing carrier data gracefully.

4. Not Formatting Numbers Before Lookup

Lookup expects E.164 format (+1XXX...). Format user input before the lookup call.

5. Overusing Caller Name Lookup

Caller name lookup has additional costs and is only available in select countries. Use carrier-only lookup when caller name is not needed.

Practice Questions

1. What information does Twilio Lookup API provide?
2. Why should you cache lookup results?
3. What does a 404 response from Lookup mean?
4. Why is number formatting important before lookup?
5. When should you use carrier-only lookup vs full lookup?

Answers:

1. Phone number format, country, carrier, line type (mobile/landline/VoIP), and caller name.
2. Each lookup is billed; caching reduces costs for repeated lookups of the same number.
3. The phone number is invalid or not found in the database.
4. Lookup expects E.164 format; unformatted numbers may return incorrect results or 404.
5. Use carrier-only lookup when you only need line type (cheaper); full lookup when you need caller name.

Challenge: Build a phone number validation service that accepts a CSV of phone numbers, looks up each one with Twilio Lookup, validates format, determines line type, and outputs a report with country, carrier, and validity status.

FAQ

Mini Project

Build a phone number validation and enrichment API endpoint that: accepts a phone number, validates format with Twilio Lookup, returns line type and carrier, and caches results in Redis for 24 hours to minimize API costs.

What's Next

Explore Twilio Verify API for phone-based authentication, or learn about Twilio phone number management for provisioning and configuring numbers.