Phone Number Carrier and Line Type with Python and the Telnyx Number Lookup

Telnyx launched a Number Lookup API that returns carrier, line type, and portability data for any phone number in a single request, and released a Python Flask example with a 24-hour in-memory cache. The tool helps developers automate call routing, SMS deliverability checks, and lead enrichment by integrating carrier data directly into applications.

Contact us https://telnyx.com/contact-us Log in https://portal.telnyx.com A phone number carrier lookup identifies the current network operator, line type, number type, and portability status tied to a phone number. Developers use it to decide whether a number can receive SMS, whether a call should route to an agent, and whether contact data is current before the first message or call goes out. The Telnyx Number Lookup API https://telnyx.com/products/number-lookup returns carrier, line type, and portability data for any phone number in a single request, using Telnyx carrier network data rather than only a third-party reseller feed. This walkthrough builds a Python Flask service that wraps that API with a 24-hour in-memory cache so repeat lookups are fast and do not create repeat API calls during the TTL. The full code is available in the Telnyx code examples repo: phone-number-lookup-python https://github.com/team-telnyx/telnyx-code-examples/tree/main/phone-number-lookup-python . The Flask app exposes three endpoints: | Method | Path | Purpose | |---|---|---| | POST | /lookup | Look up a number from a JSON body | | GET | /lookup/<phone number | Look up a number from the URL path | | GET | /cache/stats | Inspect the in-memory cache | When a lookup request arrives, the app checks the cache first. On a cache miss, it calls the Telnyx Number Lookup API, extracts carrier name, carrier type, line type, number type, and portability status, then returns a clean JSON response. Cached responses include from cache set to true . Number Lookup is a single API call: GET /v2/number lookup/{phone number} . There are no webhooks, no long-running jobs, and no polling. For endpoint details, see the Number Lookup guide https://developers.telnyx.com/docs/identity/number-lookup . +15551234567 . The example rejects numbers that do not start with + . Number lookup is not a standalone task. It is a building block for routing, trust, deliverability, and lead quality. Check carrier and line type before connecting a caller to an agent. If you route calls with Telnyx Voice API https://telnyx.com/products/voice-api , lookup results can feed programmable call routing before a caller reaches a queue. Sales teams can tell whether a prospect has a mobile line, landline, or disposable VoIP number. Teams that manage inventory through Telnyx Phone Numbers https://telnyx.com/products/phone-numbers can search, buy, and manage numbers in one place. Landlines usually cannot receive SMS. With Telnyx SMS API https://telnyx.com/products/sms-api , lookup results can keep text workflows focused on mobile-capable numbers. A number that was recently ported may point to a carrier change. That matters for compliance checks, deliverability, and customer data freshness. Free web tools are useful for one-off checks, but they usually require manual input and do not fit automated call routing, lead enrichment, or fraud screening. An API approach works inside your application, where lookup results can be cached, logged, monitored, and used in routing decisions. | Free lookup tools | Telnyx Number Lookup API | Twilio Lookup | |---|---|---| Data source: Often public or reseller data shown on a manual web page. | Data source: Telnyx carrier network data returned through API fields. | Data source: Provider lookup data returned through Twilio endpoints. | API access: Usually limited or unavailable. | API access: Yes, with carrier, line type, number type, and portability fields. | API access: Yes, through Twilio Lookup. | Cache support: Manual tools do not manage your app cache. | Cache support: Add app-side cache logic, as shown in this Flask example. | Cache support: Add app-side cache logic based on your workflow. | Integration: Best for a single manual check. | Integration: Best for Python services, routing systems, lead enrichment, and fraud checks. | Integration: Best for teams already building around Twilio. | This example uses a simple request, cache, API, response pattern. A cache hit returns local JSON. A cache miss calls Telnyx, stores the result for 24 hours, and returns the same response shape to the client. Telnyx Number Lookup pipeline Client request | v Flask /lookup endpoint | v Cache check | hit | miss v v Return cached JSON Telnyx Number Lookup API | v Store in 24h cache | v Return JSON response curl or Postman to test the endpoints 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 Edit .env and set your API key: TELNYX API KEY=KEY012...CDEF FLASK DEBUG=false Start the server: python app.py The app runs on . http://localhost:5000 http://localhost:5000 The Telnyx Python SDK https://developers.telnyx.com/development/sdk/python creates an authenticated client once at startup: client = telnyx.Telnyx api key=os.getenv "TELNYX API KEY" The core function validates the phone number format, checks the cache, and calls Telnyx on a miss. php 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 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. The Flask endpoints catch Telnyx SDK exceptions and return clear HTTP status codes: Look up a number with POST curl -X POST http://localhost:5000/lookup \ -H "Content-Type: application/json" \ -d '{"phone number": "+15551234567"}' curl http://localhost:5000/lookup/+15551234567 http://localhost:5000/lookup/+15551234567 curl http://localhost:5000/cache/stats http://localhost:5000/cache/stats Run the same lookup twice. The second response returns from cache set to true . This example uses an in-memory cache for simplicity. For production, adapt the service around your traffic patterns and data retention needs. 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 Start looking up carrier data Build carrier, line type, and portability checks into your app with Telnyx. Review the API reference https://developers.telnyx.com/api-reference/number-lookup/retrieve-lookup , then send your first lookup request. Related articles