Quickstart for Number Lookup

Look up a phone number and get carrier, line type, portability, and caller name (CNAM) in a single request. You can run a lookup three ways — the REST API, a Telnyx SDK, or the Mission Control Portal — and every method returns the same standardized response, so the output is identical no matter how you make the request:

{
  "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",
      "city": "WAUKEGAN",
      "state": "Illinois"
    }
  }
}

Now choose how you want to make the request.

Via API
Via SDK
Via Portal

Call the REST endpoint directly — no SDK required. Any HTTP client works; curl is shown here.

Replace YOUR_API_KEY with a key from the Mission Control Portal.

curl -X GET "https://api.telnyx.com/v2/number_lookup/+13129457420?type=carrier&type=caller-name" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY"

Use the type query parameter (repeat it to request several) to choose which data sets to include. Omit it for the base lookup — phone-number validation and formatting, portability, and valid_number.

The Telnyx SDKs wrap the same endpoint, so you don’t build the URL, auth header, or JSON parsing yourself. Install the SDK for your language, set your API key, and call the lookup method.

Python
Node.js
Ruby

from telnyx import Telnyx

client = Telnyx(api_key="YOUR_API_KEY")

number_lookup = client.number_lookup.retrieve(phone_number="+13129457420")
print(number_lookup.data)

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: 'YOUR_API_KEY' });

const numberLookup = await client.numberLookup.retrieve('+13129457420', { type: 'carrier' });

console.log(numberLookup.data);

require "telnyx"

telnyx = Telnyx::Client.new(api_key: "YOUR_API_KEY")

number_lookup = telnyx.number_lookup.retrieve("+13129457420")
puts(number_lookup.data)

Pass a data set with the type option (for example, "carrier"). The SDKs take a single type; to request several in one call, use the REST form above with repeated type params.

Prefer no code? Run a lookup from the Mission Control Portal:

Sign in to the Mission Control Portal.
In the left nav, go to Other Products → Number Lookup.
Enter the phone number in E.164 format (for example, +13129457420).
Run the lookup to see carrier, line type, portability, and caller name.

Next steps

What Number Lookup returns

The full set of data — carrier, line type, portability, and CNAM.

API Reference

Full endpoint documentation with request and response schemas.

Number Lookup

Verify

For AI Agents

Quickstart for Number Lookup

Next steps

What Number Lookup returns

API Reference

​Next steps

What Number Lookup returns

API Reference

Next steps