Telnyx Number Lookup API

The Telnyx Number Lookup API returns real-time data about any phone number worldwide — carrier, line type, portability, and caller name — so you can make routing, messaging, and fraud decisions before you connect or send. A single GET request returns the data sets you ask for.

What Number Lookup returns

Validation & formatting
Carrier & line type
Portability
Caller name (CNAM)
Caller identity

Every lookup returns the number’s country_code, national_format, a normalized E.164 phone_number, and a valid_number boolean — so you can validate and standardize input before you store or dial it.

Carrier — the service provider (SPID) name and, where known, the primary normalized_carrier.
Line type — mobile, fixed line, voip, toll free, and more (see the API reference for the full list) — route SMS vs. MMS or screen out number types you don’t want.
Mobile network — mobile_country_code (MCC) and mobile_network_code (MNC) for mobile numbers, on accounts enabled for MCC/MNC data.

Request with type=carrier.

For North American numbers, every lookup returns full portability detail:

ported_status and ported_date — whether and when the number was ported.
lrn (Local Routing Number) and ocn (Operating Company Name).
Current and alternate service provider: spid, spid_carrier_name, spid_carrier_type, and the altspid* equivalents.
Geographic context: city and state.

Caller name comes in two tiers — request either (or both) with the type parameter:

Standard CNAM — caller_name returns the registered CNAM caller name for US numbers. Request with type=caller-name.
Enhanced caller name — enhanced_caller_name returns a caller name with broader coverage than standard CNAM. Request with type=enhanced-caller-name.

caller_identity returns the name and postal address of the number’s owner, plus a confidence_score. Request with type=caller-identity.The confidence_score rates how strongly the number is linked to the returned name, on a scale of 50 to 90 (higher means more supporting signals). It reflects signal strength, not a probability — 70 means stronger, more consistent evidence than 60, not a 70% chance of being correct. As a guide, 70 or above is high confidence, 60 is moderate, and 50 is limited. Below 50 no name is returned, so you won’t see scores under 50.

Requesting data

type is optional — omit it for the base lookup: phone-number validation and formatting, portability (NANP numbers), and valid_number. To include additional data sets — carrier, caller name, enhanced caller name, or caller identity — pass the type query parameter; repeat it to request several.

`type` value	Returns
`carrier`	Carrier, line type, portability, and mobile network (MCC/MNC, where enabled for your account)
`caller-name`	Registered caller name (CNAM)
`enhanced-caller-name`	Enhanced caller name with broader coverage than CNAM
`caller-identity`	Name, postal address, and confidence score for the number’s owner

curl -X GET "https://api.telnyx.com/v2/number_lookup/+18005550199?type=carrier&type=caller-name" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

See the API Reference for the full request and response schema.

Example response

{
  "data": {
    "record_type": "number_lookup",
    "phone_number": "+13129457420",
    "national_format": "(312) 945-7420",
    "country_code": "US",
    "carrier": {
      "mobile_country_code": "US",
      "mobile_network_code": "866",
      "name": "Telnyx/4",
      "normalized_carrier": "Telnyx",
      "type": "voip",
      "error_code": null
    },
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": null
    },
    "portability": {
      "lrn": "2245701999",
      "ported_status": "Y",
      "ported_date": "2017-10-20",
      "ocn": "073H",
      "line_type": "voip",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "state": "Illinois"
    }
  }
}

Coverage

Data set	Coverage
Validation & formatting	Global
Carrier, line type, mobile network (MCC/MNC)	Global for mobile networks; MCC/MNC requires account enablement
Portability (LRN, OCN, SPID, ported status)	North America (NANP)
Caller name (CNAM)	United States
Enhanced caller name	United States
Caller identity	United States and Canada

Looking up Canadian numbers. By default, Number Lookup serves US numbers. Some customers also need to look up Canadian numbers — including Canadian numbers that fall under the US (NANP) region — which requires your account to be enabled for Canadian data. Until it’s enabled, those lookups return 422 ("… is a Canadian number"), regardless of type. Reach out to our support team to enable Canadian coverage for your account.

Pricing

Number Lookup is billed per lookup, and the price depends on which data sets you request with type — each data set is priced separately. See the Number Lookup pricing page for current rates.

Common use cases

Message routing — route SMS vs. MMS based on line type and carrier capabilities.
Fraud prevention — flag high-risk number types (VoIP, non-fixed) during signup or transaction verification.
2FA / OTP delivery — confirm a number is a reachable mobile line before sending a one-time passcode, so verification codes don’t fail silently.
Lead scoring — validate and enrich numbers at capture (line type, carrier, caller name) to score and prioritize leads.
Number hygiene — clean contact lists by identifying invalid or non-mobile numbers before launching campaigns.
Pre-call validation — verify number formatting and type before placing outbound calls to reduce wasted attempts.

Number Lookup

Verify

For AI Agents

Telnyx Number Lookup API

What Number Lookup returns

Requesting data

Example response

Coverage

Pricing

Common use cases

Get started

Quickstart

API Reference

​What Number Lookup returns

​Requesting data

​Example response

​Coverage

​Pricing

​Common use cases

​Get started

Quickstart

API Reference

What Number Lookup returns

Requesting data

Example response

Coverage

Pricing

Common use cases

Get started