Your Number Lookup Guide

This article will explain the Number Lookup interface on the Telnyx Mission Control portal

Dillin avatar
Written by Dillin
Updated over a week ago

The Number Lookup section of your Telnyx portal account provides a graphical interface for making number lookups. The lookups provide carrier information as well as other data such as Caller ID name info.

Please note: Number Lookup will not be available if you do not have a positive balance. you will encounter the following error.

A permission warning notice.

Video Walk-through for Number Lookup

A gif showing Number Lookup and Documentation.

Step by Step Guide to Number Lookup

The Telnyx Number Lookup API helps you know the details behind every phone number. You can use it to make each call more productive, reduce undelivered messages, and protect from spam and fraud.

Click on this button below and it will directly get you to the Number Lookup page.

Number Lookup screenshot

You are presented with one field for entering a number and a drop-down menu to select the type of number lookup type.

There are 4 options available: "Carrier", "Caller name", "Carrier and Caller name", and "None".

Fields Properties

  • "Carrier": Will return the number information and the carrier info.

  • "Caller name": Will return the number information and the Caller ID name info.

  • "Carrier and Caller name": Will return the number info, the caller ID name info and the carrier info.

  • "None": Will only return the number info.

Example

https://api.telnyx.com/v2/number_lookup/+18665552368
  • Will provide the LRN (local routing number) dip cost only.

https://api.telnyx.com/v2/number_lookup/+18665552368?type=carrier
  • Will provide the LRN dip cost and the MCC/MNC (mobile country codes and mobile network codes) dip cost. The MCC/MNC cost only applies if the number dipped is wireless/mobile.

https://api.telnyx.com/v2/number_lookup/+18665552368?type=carrier&type=caller-name
  • Will provide the LRN dip cost, the MCC/MNC dip cost (again only if the number dipped is wireless/mobile) and CNAM cost.

  • The different phone types are toll free, national, mobile and local.

The breakdown on price, using our base pricing (subject to change) for Telco Data is as follows:


Telco Data

  • "+1312270XXXX" (LRN dip @ $0.0015)

  • "?type=carrier" (MCC/MNC dip @ $0.0025, again charged only if dipped number is mobile)

  • "&type=caller-name" (CNAM dip @ $0.003)

In the above example, the total cost is $0.0015 + $0.003 = $0.0045. This is because the number dipped is not mobile or wireless, so the MCC/MNC charge is not applicable.

Please double check your telco pricing page for accurate information on your dipping costs: https://portal.telnyx.com/#/app/pricing/telco

In the field where you enter the number, you may choose the country from the drop-down menu on the left, or you can set it to "International" and you can enter any number with the leading "+" and the country code and the portal will automatically perform the lookup in the associated country.

For detailed documentation on Telnyx number lookup please see our API Reference.

As the lookup user interface is used mainly for small scale lookups and testing. Two APIs are currently available - private API and public API.

  • Public API shows part of the data we have available and can be used by everyone free of charge. Additionally, the public API does not support fetching caller name and carrier data and can be used without registration or token.

  • In order to use private API a user has to register and create an API token on Telnyx portal from here.

NOTES

  • To review your number lookup usage, you can see the charges in your invoice at the start of each new month for the previous month or you can use your usage report section as seen below. This report is not in real-time, so any dips you've made on the day, will show up on the next day.

Usage reports section of the mission control portal.
  • LRN data is not fully exposed unless you have enabled the "Permitted NPAC User" feature here: https://portal.telnyx.com/#/app/account/general

    • Please allow for 15 minutes for the changes to apply to allow you to see fully exposed LRN data.

  • We do not currently return Resporg ID information for US Toll Free number lookups.

Sub member / account / user permissions

  • Account organization owners have permission to see and enable the "Permitted NPAC User" feature, sub members do not.

  • The Number Lookup tool is not available for sub members / sub users of an organisation at this moment in time.

    • This applies to both the lookup service on the portal and through our API when using the API key of a subuser.

Account information showing Permitted NPAC User.

Did this answer your question?