twilio-lookup

What this skill does

# twilio-lookup

## Purpose

`twilio-lookup` enables production-grade phone intelligence workflows using Twilio Lookup: validating phone numbers, normalizing to E.164, retrieving carrier metadata, line type (mobile/landline/VoIP), and caller ID / CNAM (where supported). Engineers use this to:

- Reject invalid or unreachable numbers before sending SMS/WhatsApp/Voice (reduce 21211/30003 failures and cost).
- Route traffic by line type (e.g., avoid SMS to landlines; choose Voice fallback for VoIP-heavy regions).
- Enforce geo/region policy (e.g., block high-risk countries, require US/CA for 10DLC).
- Enrich user profiles with carrier + caller name for fraud scoring and support tooling.
- Build deterministic normalization pipelines (E.164 + country code) across services.

This guide assumes you are integrating Lookup into a larger Twilio production stack (Messaging/Voice/Verify/Studio/SendGrid), with strong error handling, rate limiting, and security controls.

---

## Prerequisites

### Accounts & API credentials

- Twilio Account SID (format `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
- Twilio Auth Token
- Optional: Twilio API Key + Secret (recommended over Auth Token for production)
  - API Key SID format `SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

Create API Key:
- Twilio Console → **Account** → **API keys & tokens** → **Create API key**
- Store secrets in a secret manager (AWS Secrets Manager, GCP Secret Manager, Vault). Do not commit.

### Twilio Lookup API

- Lookup API v2 is the current recommended API surface.
- Some fields (e.g., caller name) may require add-ons or are region-dependent.

### Runtime versions (tested)

- Node.js: **20.11.1** (LTS)
- Python: **3.11.8**
- Java: **17.0.10** (Temurin)
- Go: **1.22.1**
- Twilio helper libraries:
  - twilio-node: **4.23.0**
  - twilio-python: **9.4.1**
- Twilio CLI (optional but useful): **5.19.0**

### OS support

- Ubuntu 22.04 LTS (x86_64)
- Fedora 39 (x86_64)
- macOS 14 Sonoma (Intel + Apple Silicon)

### Network & TLS

- Outbound HTTPS to `lookups.twilio.com` (and `api.twilio.com` for auth/other services).
- TLS inspection proxies must allow SNI and modern ciphers; otherwise expect intermittent `ECONNRESET`/handshake failures.

---

## Core Concepts

### Mental model: “Normalize → Enrich → Decide → Act”

1. **Normalize**: Convert user input to E.164 (e.g., `+14155552671`) and validate plausibility.
2. **Enrich**: Fetch metadata (carrier, line type, caller name).
3. **Decide**: Apply policy (allow/deny, route to SMS vs Voice, require Verify).
4. **Act**: Send message/call/verification; store enrichment for audit and future routing.

### Lookup API entities

- **Phone number**: input can be local/national; output should be E.164.
- **Fields**: optional expansions that increase cost/latency.
  - Common fields:
    - `line_type_intelligence` (line type + carrier)
    - `caller_name` (CNAM-like data where available)
- **Country code**: influences parsing when input is not E.164.

### Architecture overview

Typical production flow:

- Edge/API receives `phone` string.
- Service normalizes and validates using Lookup.
- Result stored in a user profile table with:
  - `e164`, `country_code`, `national_format`
  - `line_type`, `carrier_name`, `mobile_country_code`, `mobile_network_code`
  - `caller_name` (if used)
  - `lookup_timestamp`, `lookup_version`, `risk_flags`
- Downstream:
  - Messaging service chooses Messaging Service SID with geo-matching.
  - Verify uses normalized E.164.
  - Voice uses E.164 and optionally SIP routing.

### Cost and latency tradeoffs

- Basic number validation is cheaper than requesting additional fields.
- `fields=line_type_intelligence` adds extra lookup work; cache results.
- `fields=caller_name` can be slower and less reliable; use only when needed.

### Caching strategy

- Cache by E.164 for a TTL (e.g., 7–30 days) depending on your risk tolerance.
- Carrier and line type can change (porting). For high-risk flows, re-check on critical events (password reset, payout).

---

## Installation & Setup

### Official Python SDK — Lookup

**Repository:** https://github.com/twilio/twilio-python  
**PyPI:** `pip install twilio` · **Supported:** Python 3.7–3.13

```python
from twilio.rest import Client
client = Client()

# Basic lookup
phone = client.lookups.v2.phone_numbers("+15558675309").fetch()
print(phone.country_code, phone.phone_number)

# With add-ons
phone = client.lookups.v2.phone_numbers("+15558675309").fetch(
    fields=["line_type_intelligence", "caller_name", "sim_swap"]
)
print(phone.line_type_intelligence)  # {"type": "mobile", "error_code": null}
print(phone.caller_name)             # {"caller_name": "Alice", "error_code": null}
```

Source: [twilio/twilio-python — lookups](https://github.com/twilio/twilio-python/blob/main/twilio/rest/lookups/)

### 1) Install Twilio CLI (optional but recommended)

#### Ubuntu 22.04 (x86_64)

```bash
curl -sSL https://twilio-cli-prod.s3.amazonaws.com/twilio-cli-linux-x86_64.tar.gz -o /tmp/twilio.tar.gz
sudo tar -xzf /tmp/twilio.tar.gz -C /usr/local/bin twilio
twilio --version
```

#### Fedora 39 (x86_64)

```bash
curl -sSL https://twilio-cli-prod.s3.amazonaws.com/twilio-cli-linux-x86_64.tar.gz -o /tmp/twilio.tar.gz
sudo tar -xzf /tmp/twilio.tar.gz -C /usr/local/bin twilio
twilio --version
```

#### macOS (Intel + Apple Silicon) via Homebrew

```bash
brew update
brew install twilio/brew/twilio
twilio --version
```

### 2) Authenticate Twilio CLI

Preferred: API Key

```bash
twilio login --apikey YOUR_API_KEY_SID --apisecret 'your_api_key_secret' --profile prod
twilio profiles:list
```

Alternative: Account SID + Auth Token

```bash
twilio login --sid YOUR_ACCOUNT_SID --token 'your_auth_token' --profile prod
```

### 3) Install helper libraries

#### Node.js (20.11.1)

```bash
node --version
npm --version

mkdir -p twilio-lookup-demo-node && cd twilio-lookup-demo-node
npm init -y
npm install [email protected] [email protected]
```

#### Python (3.11.8)

```bash
python3 --version
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip==24.0
pip install twilio==9.4.1 httpx==0.27.0
```

### 4) Environment variables

Set in your shell (dev) or secret manager (prod):

```bash
export TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID"
export TWILIO_AUTH_TOKEN="your_auth_token"
# or API key auth:
export TWILIO_API_KEY_SID="YOUR_API_KEY_SID"
export TWILIO_API_KEY_SECRET="your_api_key_secret"
```

### 5) Verify connectivity

```bash
curl -sS https://lookups.twilio.com/ -I | head
```

Expect `HTTP/2 404` or similar (root path not found is fine); the goal is TLS connectivity.

---

## Key Capabilities

### Number validation + E.164 normalization

- Accept user input in various formats.
- Use `countryCode` when input is not E.164.
- Persist normalized E.164 and derived country.

Key output fields:
- `phone_number` (E.164)
- `national_format`
- `country_code`
- `valid` (v1) / v2 semantics vary; treat as “lookup succeeded” + parse results.

### Carrier lookup + line type intelligence

Use `fields=line_type_intelligence` to retrieve:
- `line_type` (e.g., `mobile`, `landline`, `voip`, `nonFixedVoip`, `tollFree`)
- `carrier_name`
- `mobile_country_code` (MCC)
- `mobile_network_code` (MNC)
- `error_code` (carrier-specific issues)

Production uses:
- Route SMS only to `mobile`/`nonFixedVoip` depending on policy.
- Flag `voip` for fraud scoring (common in account takeovers).
- Detect toll-free and apply different messaging rules.

### Caller ID / CNAM (caller_name)

Use `fields=caller_name` (availability varies by country and number type).

Typical use:
- Support tooling (display “likely name”).
- Fraud heuristics (mismatch between claimed name and CNAM).

Do not treat CNAM as authoritative identity.

### Policy enforcement (geo + risk)

Combine Lookup results with:
- Country allow/deny lists
- Known high-risk carriers
- VoIP restrictions for sensitive actions
- 10DLC constraints (US A2P messaging requires registration; Lookup helps ensure US numbers are actually US)