twilio-lookup-phone-intelligence

Overview

Twilio Lookup validates phone numbers and provides optional intelligence packages. Basic validation is free; data packages (line type, SIM swap, etc.) are paid per lookup.

---

Prerequisites

• Twilio account (free trial works for basic lookups) — New to Twilio? See twilio-account-setup
• Environment variables:
  • TWILIO_ACCOUNT_SID
  • TWILIO_AUTH_TOKEN — See twilio-iam-auth-setup for credential setup and best practices
• SDK: pip install twilio / npm install twilio

---

Quickstart

Python

import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

phone = client.lookups.v2.phone_numbers("+15108675310").fetch()

print(phone.valid)            # True / False
print(phone.phone_number)     # +15108675310 (E.164)
print(phone.national_format)  # (510) 867-5310
print(phone.country_code)     # US

Node.js

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

const phone = await client.lookups.v2.phoneNumbers("+15108675310").fetch();

console.log(phone.valid);
console.log(phone.phoneNumber);
console.log(phone.nationalFormat);

If valid is false, check phone.validationErrors for the reason.

---

Key Patterns

Line Type Intelligence (paid)

Identifies mobile, landline, VoIP, toll-free, etc.

Python

phone = client.lookups.v2.phone_numbers("+15108675310").fetch(
    fields="line_type_intelligence"
)
print(phone.line_type_intelligence)
# {'type': 'mobile', 'carrier_name': 'T-Mobile USA', ...}

Node.js

const phone = await client.lookups.v2.phoneNumbers("+15108675310").fetch({
    fields: "line_type_intelligence",
});
console.log(phone.lineTypeIntelligence);

Line types: mobile, landline, voip, toll-free, fixedVoip, nonFixedVoip, personal, payphone, unknown

Multiple Packages in One Request

Python

phone = client.lookups.v2.phone_numbers("+15108675310").fetch(
    fields="line_type_intelligence,sim_swap,caller_name"
)

Node.js

const phone = await client.lookups.v2.phoneNumbers("+15108675310").fetch({
    fields: "line_type_intelligence,sim_swap,caller_name",
});

Validate Before Sending

Python

phone = client.lookups.v2.phone_numbers("+invalid").fetch()
if not phone.valid:
    print(f"Invalid number: {phone.validation_errors}")
    # Handle gracefully — do not attempt to send

Node.js

const phone = await client.lookups.v2.phoneNumbers("+invalid").fetch();
if (!phone.valid) {
    console.log("Invalid number:", phone.validationErrors);
}

Available Data Packages

Package	fields value	Coverage	Use case
Line Type Intelligence	line_type_intelligence	Worldwide	Route by line type; block VoIP
Caller Name	caller_name	US only	Show caller ID
SIM Swap	sim_swap	Select regions	Fraud detection
Identity Match	identity_match	Select regions	Verify ownership
SMS Pumping Risk	sms_pumping_risk	Worldwide	Fraud prevention
Reassigned Number	reassigned_number	US only	Check if recycled

---

Common Errors

Code	Meaning	Fix
20404	Phone number not found	Number may be invalid or unsupported format
60601	Data package not available for this region	Check regional coverage before requesting package

---

CANNOT

• Cannot look up by name or address — Input is always a phone number. No reverse search.
• Cannot get caller_name for non-US numbers — Returns error 60600 (out of coverage).
• Cannot detect conditional call forwarding — Only unconditional forwarding is detected, and only for UK carriers.
• Cannot guarantee SIM swap data without carrier registration — Returns error 60606 until carrier approval is in place.
• Cannot use Reassigned Number outside the US — US-only dataset with monthly update cadence.
• Cannot get real-time SMS pumping scores — Scores are statistical models, not live traffic analysis.
• Cannot write data — Lookup v2 is read-only (GET only). The one exception is Line Type Override (POST/DELETE).
• Cannot batch multiple phone numbers in one request — One number per API call. Loop for bulk lookups.
• Cannot avoid billing on caller_name requests that return no data — Billed per request regardless of whether data is returned.
• Cannot use Phone Number Quality Score or Pre-fill without provisioning — Returns 60606. Contact Twilio sales to enable.
• Cannot guarantee deliverability from a valid lookup — A valid number may still be unreachable (carrier issues, ported, etc.)

---

Next Steps

• Send SMS after validation: twilio-sms-send-message
• Send OTP after validation: twilio-verify-send-otp