Look Up Phone Number Carrier and Line Type with Python

Telnyx Number Lookup pipeline

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/phone-number-lookup-python
cp .env.example .env
pip install -r requirements.txt

TELNYX_API_KEY=KEY012...CDEF
FLASK_DEBUG=false

python app.py

client = telnyx.Telnyx(api_key=os.getenv("TELNYX_API_KEY"))

The lookup function

The core function validates the phone number format, checks the cache, and calls Telnyx on a miss.

def lookup_phone_number(phone_number: str) -> dict:
    if not phone_number.startswith("+"):
        raise ValueError("Phone number must be in E.164 format (e.g., +15551234567)")

cached_result = get_cached_lookup(phone_number)
if cached_result:
    cached_result["from_cache"] = True
    return cached_result

response = client.number_lookup.retrieve(phone_number)

lookup_data = {
    "phone_number": response.data.phone_number,
    "country_code": response.data.country_code,
    "carrier": {
        "name": response.data.carrier.name if response.data.carrier else None,
        "type": response.data.carrier.type if response.data.carrier else None,
    },
    "line_type": response.data.line_type,
    "number_type": response.data.number_type,
    "portability": {
        "status": response.data.portability.status if response.data.portability else None,
        "last_checked_at": response.data.portability.last_checked_at if response.data.portability else None,
    },
    "from_cache": False,
}

cache_lookup_result(phone_number, lookup_data)
return lookup_data</code></pre>

Caching

The cache is a Python dict with a 24-hour TTL. Each entry stores the lookup result and a timestamp. is_cache_valid() compares the stored timestamp against the TTL, and expired entries are replaced on the next lookup.

This keeps repeated lookups of the same number free of repeat API calls during the 24-hour window.

Error handling

The Flask endpoints catch Telnyx SDK exceptions and return clear HTTP status codes:

• 401 for invalid API keys
• 429 for rate limit hits
• 503 for network errors
• 400 for malformed requests

Test the endpoints

# Look up a number with POST
curl -X POST http://localhost:5000/lookup \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+15551234567"}'

Look up a number with GET

curl http://localhost:5000/lookup/+15551234567

Check the cache

curl http://localhost:5000/cache/stats

Run the same lookup twice. The second response returns from_cache set to true.

Going to production

This example uses an in-memory cache for simplicity. For production, adapt the service around your traffic patterns and data retention needs.

• Shared cache: Replace the in-memory dict with Redis so cached data survives restarts and is shared across instances.
• Authentication: Add API key validation on your endpoints so the lookup service is not open to the internet.
• Rate limiting: Protect your endpoints and stay within Telnyx Number Lookup limits.
• Persistence: Store lookup history in a database if you need an audit trail.
• Monitoring: Add structured logging and alert on error rates.
• Call routing: If you connect existing PBX traffic through Telnyx SIP Trunking, lookup results can feed pre-call routing rules before traffic reaches your queue.

Resources

• Code example: phone-number-lookup-python
• Number Lookup guide
• API reference
• Python SDK
• Telnyx Portal

Related examples

• number-lookup-fraud-screener-python for screening inbound numbers before connecting
• number-lookup-lead-enrichment-python for enriching sales leads with carrier and CNAM data
• cnam-caller-id-lookup-enrichment-python for caller ID enrichment
• bulk-number-validation-cleaner-python for validating and cleaning lists of numbers

Phone number carrier lookup FAQ