{"slug": "phone-number-carrier-and-line-type-with-python-and-the-telnyx-number-lookup", "title": "Phone Number Carrier and Line Type with Python and the Telnyx Number Lookup", "summary": "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.", "body_md": "[Contact us](https://telnyx.com/contact-us)\n\n[Log in](https://portal.telnyx.com)\n\nA **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.\n\nThe 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.\n\nThe 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).\n\nThe Flask app exposes three endpoints:\n\n| Method | Path | Purpose |\n|---|---|---|\n| POST | `/lookup` | Look up a number from a JSON body |\n| GET | `/lookup/<phone_number>` | Look up a number from the URL path |\n| GET | `/cache/stats` | Inspect the in-memory cache |\n\nWhen 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`\n\nset to `true`\n\n.\n\nNumber Lookup is a single API call: `GET /v2/number_lookup/{phone_number}`\n\n. 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).\n\n`+15551234567`\n\n. The example rejects numbers that do not start with `+`\n\n. Number lookup is not a standalone task. It is a building block for routing, trust, deliverability, and lead quality.\n\nCheck 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.\n\nSales 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.\n\nLandlines 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.\n\nA number that was recently ported may point to a carrier change. That matters for compliance checks, deliverability, and customer data freshness.\n\nFree 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.\n\n| Free lookup tools | Telnyx Number Lookup API | Twilio Lookup |\n|---|---|---|\nData 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. |\nAPI access: Usually limited or unavailable. | API access: Yes, with carrier, line type, number type, and portability fields. | API access: Yes, through Twilio Lookup. |\nCache 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. |\nIntegration: 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. |\n\nThis 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.\n\n```\nTelnyx Number Lookup pipeline\n```\n\n[Client request]\n|\nv\n[Flask /lookup endpoint]\n|\nv\n[Cache check]\n| hit | miss\nv v\n[Return cached JSON] [Telnyx Number Lookup API]\n|\nv\n[Store in 24h cache]\n|\nv\n[Return JSON response]\n\n`curl`\n\nor Postman to test the endpoints\n\n```\ngit clone https://github.com/team-telnyx/telnyx-code-examples.git\ncd telnyx-code-examples/phone-number-lookup-python\ncp .env.example .env\npip install -r requirements.txt\n```\n\nEdit `.env`\n\nand set your API key:\n\n```\nTELNYX_API_KEY=KEY012...CDEF\nFLASK_DEBUG=false\n```\n\nStart the server:\n\n```\npython app.py\n```\n\nThe app runs on\n\n.[http://localhost:5000](http://localhost:5000)\n\nThe Telnyx [Python SDK](https://developers.telnyx.com/development/sdk/python) creates an authenticated client once at startup:\n\n```\nclient = telnyx.Telnyx(api_key=os.getenv(\"TELNYX_API_KEY\"))\n```\n\nThe core function validates the phone number format, checks the cache, and calls Telnyx on a miss.\n\n``` php\ndef lookup_phone_number(phone_number: str) -> dict:\n    if not phone_number.startswith(\"+\"):\n        raise ValueError(\"Phone number must be in E.164 format (e.g., +15551234567)\")\ncached_result = get_cached_lookup(phone_number)\nif cached_result:\n    cached_result[\"from_cache\"] = True\n    return cached_result\n\nresponse = client.number_lookup.retrieve(phone_number)\n\nlookup_data = {\n    \"phone_number\": response.data.phone_number,\n    \"country_code\": response.data.country_code,\n    \"carrier\": {\n        \"name\": response.data.carrier.name if response.data.carrier else None,\n        \"type\": response.data.carrier.type if response.data.carrier else None,\n    },\n    \"line_type\": response.data.line_type,\n    \"number_type\": response.data.number_type,\n    \"portability\": {\n        \"status\": response.data.portability.status if response.data.portability else None,\n        \"last_checked_at\": response.data.portability.last_checked_at if response.data.portability else None,\n    },\n    \"from_cache\": False,\n}\n\ncache_lookup_result(phone_number, lookup_data)\nreturn lookup_data</code></pre>\n```\n\nThe cache is a Python dict with a 24-hour TTL. Each entry stores the lookup result and a timestamp. `is_cache_valid()`\n\ncompares the stored timestamp against the TTL, and expired entries are replaced on the next lookup.\n\nThis keeps repeated lookups of the same number free of repeat API calls during the 24-hour window.\n\nThe Flask endpoints catch Telnyx SDK exceptions and return clear HTTP status codes:\n\n```\n# Look up a number with POST\ncurl -X POST http://localhost:5000/lookup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"phone_number\": \"+15551234567\"}'\n```\n\ncurl [http://localhost:5000/lookup/+15551234567](http://localhost:5000/lookup/+15551234567)\n\ncurl [http://localhost:5000/cache/stats](http://localhost:5000/cache/stats)\n\nRun the same lookup twice. The second response returns `from_cache`\n\nset to `true`\n\n.\n\nThis example uses an in-memory cache for simplicity. For production, adapt the service around your traffic patterns and data retention needs.\n\n`number-lookup-fraud-screener-python`\n\nfor screening inbound numbers before connecting`number-lookup-lead-enrichment-python`\n\nfor enriching sales leads with carrier and CNAM data`cnam-caller-id-lookup-enrichment-python`\n\nfor caller ID enrichment`bulk-number-validation-cleaner-python`\n\nfor 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.\n\nRelated articles", "url": "https://wpnews.pro/news/phone-number-carrier-and-line-type-with-python-and-the-telnyx-number-lookup", "canonical_source": "https://telnyx.com/resources/phone-number-carrier-lookup-python", "published_at": "2026-07-01 10:47:26+00:00", "updated_at": "2026-07-01 11:20:37.932087+00:00", "lang": "en", "topics": ["developer-tools", "ai-infrastructure"], "entities": ["Telnyx", "Twilio", "Python", "Flask", "Number Lookup API", "Voice API", "SMS API"], "alternates": {"html": "https://wpnews.pro/news/phone-number-carrier-and-line-type-with-python-and-the-telnyx-number-lookup", "markdown": "https://wpnews.pro/news/phone-number-carrier-and-line-type-with-python-and-the-telnyx-number-lookup.md", "text": "https://wpnews.pro/news/phone-number-carrier-and-line-type-with-python-and-the-telnyx-number-lookup.txt", "jsonld": "https://wpnews.pro/news/phone-number-carrier-and-line-type-with-python-and-the-telnyx-number-lookup.jsonld"}}