> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telnyx Number Lookup API

> Use the Telnyx Number Lookup API to retrieve carrier, line type, and portability data for any phone number worldwide before routing or messaging.

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

> [tab] Validation & formatting
>
> 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.

> [tab] Carrier & line type
>
> * **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`.

> [tab] Portability
>
> 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`.

> [tab] Caller name (CNAM)
>
> 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`.

> [tab] Caller identity
>
> `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, plus entity type (`Person` / `Business`) |
| `caller-identity` | Name, postal address, and confidence score for the number's owner |

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

See the [API Reference](https://developers.telnyx.com/api-reference/number-lookup/lookup-phone-number-data.md) for the full request and response schema.

### Example response

```json theme={null}
{
  "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
    },
    "enhanced_caller_name": {
      "caller_name": "TELNYX LLC",
      "entity_type": "Business",
      "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 |

> [!NOTE]
>
> **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](https://telnyx.com/pricing/number-lookup) 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.

## Get started

> [card] [Quickstart](https://developers.telnyx.com/docs/identity/number-lookup/quickstart.md)
>
> Look up your first phone number in a few lines of code.

> [card] [API Reference](https://developers.telnyx.com/api-reference/number-lookup/lookup-phone-number-data.md)
>
> Full endpoint documentation with request and response schemas.