openai/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