HLR Number Lookup API

From txtNation Wiki
Revision as of 13:44, 20 June 2016 by AshleyCross (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


Having accurate data is critical for enabling and supporting precise and, more importantly, cost-effective communications with your customers. txtNation’s Number lookup platform enables companies to retrieve highly accurate and efficient network information directly from the GSM network in real time.



Any country connection problems or interruptions to txtNation services will be announced in our Zendesk forum article found here: Please login to / create your Zendesk account and subscribe to these updates now, they will be very important for your services. If you are a temporary developer on a project, please advise your employer to do the same. Scheduled maintenance periods can also be subscribed to here.


What can you do?

Using the Number Lookup platform, you are able to create dynamic and efficient applications to achieve various goals, including:

  • Validating the integrity of mobile subscribers in your database, allowing you to remove invalid numbers
  • Optimising message and call-routing by directing SMS messages to the correct network
  • Preventing fraud by implementing ID verification
  • Validating the location of subscribers with accurate MNC/MCC checking, even if the subscriber has ported from another network


To implement and use txtNation’s Number Lookup platform the client should have certain resources available that are not provided by txtNation. For example, a developer must be able to plan and implement:

  • The sending of an HTTP request that transports the lookup to txtNation’s platform (http://www.w3.org/Protocols/rfc2616/rfc2616.html).
  • Optionally, for asynchronous lookups, a service must be embedded into the client's web server to process delivery reports sent by txtNation.


txtNation’s Number Lookup platform allows clients to communicate using simple HTTP GET requests, modifying the application functionality via an array of HTTP parameters. In general, HTTP is easy to implement and maintain but other communication methods may be available on request.

Results from the lookup are provided in a line-by-line, key=value format by default, although, as with the communication method, more result formats could be made available on request.

If required, an HTTPS interface can also be provided for clients who require secure connectivity with txtNation.


Authentication to the service is performed using two parameters that will be supplied to clients by txtNation. These parameters are required on every lookup performed. txtNation’s Number Lookup platform also supports secure transactions over HTTPS if required.

Where possible, txtNation strongly recommends the use of a fixed IP address when communicating with the Number Lookup platform.

Detailed Communication Process

The following section describes each step of the communication process.

Synchronous GET Requests

In essence, these two types of request are identical. Care should be taken when sending communications to the correct page; a GET receiver does not read information in the POST request, and vice versa.

Transport URLs

Depending on the type of credits you have purchased please choose between Real-time Lookup and Number Portability Lookup locations, each has a set of transport methods to choose from

Real-time Lookup (RTLU)

This allows you to check the mobile network and if the phone is currently connected to the network.


  • For HTTP GET requests:


Number Portability Lookup

This allows you to accertain only the mobile network.


  • For HTTPS GET requests:



The parameters that you should send through to manipulate the output of txtNation's Number Lookup platform are listed below:

Name Required? Comments
user Yes The username provided to you by txtNation
password Yes The password provided to you by txtNation
msisdn Yes The subscriber's mobile number
return No The type of output to return in the response body. The acceptable values for this field are: csv, json and xml.
Please note that if you are using a premium route then only JSON and XML return types are supported.

Return Values

By default, the results of the lookup are available in the body of the response in a line-by-line, key=value format. For example, a typical result may be formatted as follows:

--START:447777777777 status="ok" mcc="234" mnc="02" operatorname="Telefónica O2 UK Ltd" isoalpha3code="GBR" END:447777777777--

Any future information added about a subscriber’s network will be contained inside the result envelope and will not interfere with existing result variables.

Return Values: An Explanation

With reference to the example result provided above:

  • --START:447777777777

The result itself is encapsulated between a START and an END tag. All information available about the subscriber's network is between these two tags.

  • status="ok"

The status of the lookup determines if the lookup was successful. Unsuccessful lookups will return a “nok” value in this status parameter. You may retry unsuccessful responses later. The most common cause of the status="nok" error is that the subscriber’s handset is switched off or that they are out of their network’s coverage range.

  • mcc="234"

The Mobile Country Code that the subscriber belongs to (see http://en.wikipedia.org/wiki/ Mobile_Country_Code).

  • mnc="02"

The Mobile Network Code that determines which network the subscriber belongs to (http:// en.wikipedia.org/wiki/Mobile_Network_Code)

  • operatorname="Telefónica O2 UK Ltd"

The textual representation of the subscriber's network.

  • isoalpha3code="GBR"

The ISO 3166-1 alpha-3 code of the country that the network of the subscriber belongs to (see http:// en.wikipedia.org/wiki/ISO_3166-1_alpha-3).

  • --END:447777777777

The end of the result envelope for this subscriber's network details.

Other Return Values: An Explanation

If you are using the real-time lookup, these results will also be present.

  • imsi="23402"

The IMSI number of the mobile subscriber. (RTLU only)

  • power="on"

Whether the handset is currently powered on. Values can be "on" or "off". (RTLU only)

  • error_code=

The error_code parameter will be present if there was an error in the request. Generally, this means that the request was successful but the data provided was incorrect or invalid. In the case of an invalid MSISDN being provided, you will see the error_code parameter set to "UNKNOWN_SUBSCRIBER". Note: The "status" parameter can be set to "ok" if the request was successful even if there is an error set. Typically this means you do not need to retry the request as the status of the look up will not change.
Please refer to the following table for possible error codes.

Result Description
OK The request was successful
DATA_MISSING The data was missing
UNKNOWN_SUBSCRIBER The subscriber is unknown
CALL_BARRED The service is restricted by the destination network
ABSENT_SUBSCRIBER_SM The subscriber is absent
UNEXPECTED_DATA_VALUE An unexpected data value in the request
SYSTEM_FAILURE A system failure occurred in the HLR
FACILITY_NOT_SUPPORTED Short message facility is not supported
TELE_SERVICE_NOT_PROVISIONED SMS teleservice is not provisioned
HLR_REJECT The HLR request was rejected
HLR_ABORT The HLR (or some other entity) aborted the request. No
response to the request was received
HLR_LOCAL_CANCEL No response for the HLR request was received.
RETURN_TYPE_NOT_SUPPORTED You must use xml or json as your return type if you are using a premium route
TIMEOUT No response to the request was received
REQUEST_THROTTLED Maximum ongoing requests exceeded
IMSI_LOOKUP_BLOCKED Request is blocked
Mandatory parameter msisdn not found Some mandatory parameter are missing in the request
MSISDN range is not accepted The number are not allowed on this service
msisdn is invalid Wrong format of the MSISDN parameter

Premium Return Values

If you are using a premium route for your requests then the return format is slightly different. You are able to discover the following extra bits of information:

    447777777777: {

        original_network: {
            mcc: "234",
            mnc: "30",
            operatorname: "T-Mobile (UK) Limited",
            isoalpha3code: "GBR"

        current_network: {
            mcc: "234",
            mnc: "02",
            operatorname: "Telefonica O2 UK Limited",
            isoalpha3code: "GBR"

        subscription_network: {

            imsi_network: {
                mcc: "234",
                mnc: "10",
                operatorname: "Telefonica O2 UK Limited",
                isoalpha3code: "GBR"

            hlr_network: {
                mcc: "234",
                mnc: "02",
                operatorname: "Telefonica O2 UK Limited",
                isoalpha3code: "GBR"

        presence: 1,
        ported: 1,
        roaming: 0,
        ss7error: 0,
        status: "ok"

The above example shows an MSISDN that originally belonged to the T-Mobile network in the UK but has been ported to Telefonica O2.

Original_Network - The mobile network that owns the number prefix, which can be taken as the end users original network.

Current_Network - The mobile network to which the end user is currently connected.

Subscription_Network - There are two subcategories to this section: imsi_network and hlr_network. The first, imsi_network, is the mobile network to which the IMSI is connected. The second, hlr_network, is the mobile network that the end user is connected to according to the HLR. These fields can differ if the mobile network has multiple Mobile Network Codes (MNC) codes in a country.

Presence - Indicates whether the end user's handset is currently switched on. Please note that this information comes directly from the Mobile Switching Centre (MSC) not the handset itself. Consequently a handset can take several hours before it is recognised as being powered off.

Ported - A flag that determines if the MSISDN been ported

Roaming - A flag to determine if the end user is currently roaming abroad or otherwise

ss7error - A flag that indicates an SS7 error

VLR Lookup

Visitor Location Register contains the international mobile subscriber identity (IMSI) and the MSISDN of which helps to interpret the location of the mobile subscriber *

Please contact your account manager for more information on activating this service.


Q: The result of my lookup returns a status="ok" response but contains no network details. What's going on?
A: If this scenario occurs, the most likely explanation is that the subscriber's MSISDN does not exist, or that the number is incorrectly formatted in the lookup. The format for the number you communicate to txtNation can be any of the following types: 447777777777, +447777777777, 00447777777777 (where 44 or 0044 is the international dial code for the United Kingdom). txtNation's preference is an MSISDN in the format: 447777777777.

A: In the above scenario for the RTLU there may be additional information available RTLU additional Information

Q: Does the subscriber's phone need to be switched on for the lookup platform to function properly?
A: Yes it does. As txtNation queries the handset directly through the GSM network provider, the handset must be switched on and must be within coverage.

Q: How can I purchase credits for the Number Lookups?
A: You should contact your account manager to purchase more credits for number lookups. txtNation is developing a control panel that will allow clients to purchase credits on an adhoc basis, and this will be made available in due course.

Q: I have a problem that's not addressed in this API. How can I contact your support team?
A: If you require assistance with your setup, please log a client support ticket at: http://clients.txtnation.com/. A ticket will be assigned to a support agent within the hour, and a reply sent within 24 hours.


The following .php example can be downloaded for reference only:


 The example includes place holders for `username` and `password` you will need to contact 
a txtNation Account Manager, to obtain a working set of credentials.
Personal tools