Back to Blog
Language How-Tos

How to Look Up a Phone Number Carrier and Type in Twilio Using Python

Use the Twilio Lookup API in Python to check if a number is mobile or landline, get carrier information, and validate numbers before sending.

DA
Danial A
Senior Twilio Consultant, Telphi Consulting
June 22, 2026
8 min read
Twilio
Python
How-To
Code
How to Look Up a Phone Number Carrier and Type in Twilio Using Python

This tutorial uses the Twilio Lookup API in Python to validate phone numbers, determine their line type (mobile, landline, or VoIP), and retrieve carrier information before sending messages or making calls. It targets developers who want to pre-filter recipient lists to avoid wasting spend on landlines that cannot receive SMS. You will query the Lookup API with a single phone number and inspect the structured response to make routing decisions in your application.

Prerequisites and Setup

You need Python 3.7 or higher, the Twilio SDK installed with pip install twilio python-dotenv, and your Twilio credentials in a .env file. The Lookup API is a paid add-on; each lookup incurs a small per-request cost, so do not call it on every page load. Store your Account SID and Auth Token in environment variables; the Lookup API uses the same client authentication as the rest of the Twilio SDK. The line_type_intelligence field is what distinguishes mobile from landline numbers, so you must explicitly request it using the fields parameter.

pip install twilio python-dotenv

# .env
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here

The Complete Code

The Lookup v2 API endpoint is accessed through client.lookups.v2.phone_numbers(number).fetch(), where number is the E.164-formatted phone number you want to look up. Passing fields="line_type_intelligence" adds carrier and line type data to the response in the line_type_intelligence dictionary. The type key inside that dictionary returns values like mobile, landline, voip, or nonFixedVoip. If the number is invalid, Twilio raises a TwilioRestException with a 404 status rather than returning a result object.

import os
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
from dotenv import load_dotenv

load_dotenv()

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

def lookup_number(phone_number: str) -> dict:
    try:
        result = client.lookups.v2.phone_numbers(phone_number).fetch(
            fields="line_type_intelligence"
        )
        lti = result.line_type_intelligence or {}
        return {
            "valid":        result.valid,
            "phone_number": result.phone_number,
            "country_code": result.country_code,
            "line_type":    lti.get("type"),
            "carrier":      lti.get("carrier_name"),
            "error_code":   lti.get("error_code"),
        }
    except TwilioRestException as e:
        return {"valid": False, "error": e.msg}

info = lookup_number("+15551234567")
print(info)

if info.get("valid") and info.get("line_type") == "mobile":
    print("Safe to send SMS to this number.")
else:
    print("Number is not a mobile line; skip SMS.")

Testing and Debugging

Test with a known mobile number, a landline, and a VoIP number (such as a Google Voice number) to verify the line_type field returns different values for each. If line_type_intelligence is None in the response, you may have forgotten to include the fields parameter in the fetch call. A TwilioRestException with status 404 means the number format was invalid or the number does not exist; always validate E.164 format locally before calling the API. Monitor your Twilio account usage to ensure lookup volume stays within your budget, particularly if you are batch-validating large contact lists.

Taking It Further

Build a pre-send validation function that filters a bulk recipient list and removes landline numbers before the SMS sending loop runs. Add CNAM lookup by including fields="caller_name" to retrieve the registered name associated with the number for caller ID data. Cache lookup results in a database keyed by phone number with a TTL of several days, since carrier assignments rarely change, to reduce per-lookup API costs. Combine number validation with the Verify API to build a registration flow that only accepts mobile numbers capable of receiving SMS OTPs.

Talk to Telphi Consulting about building smart pre-send validation pipelines that improve deliverability and reduce messaging costs.

Share this article:
0 views

Ready to Transform Your Business Communications?

Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.

Comments (0)

Join the discussion and share your thoughts (AI-moderated for quality)

Protected by AI moderation

Be the first to comment

No comments yet. Share your thoughts below.