HLR Number Lookup API

Introduction

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.

IMPORTANT INFORMATION

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
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.

Requirements

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.

Technologies

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.

Security

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.

URLs:

For HTTP GET requests:

http://api.txtnation.com/Networks/RTLU/get.php

Number Portability Lookup

This allows you to accertain only the mobile network.

URLs:

For HTTPS GET requests:

https://api.txtnation.com/Networks/Lookup/get.php

Parameters

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 and xml

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)

Troubleshooting

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 or0044 is the international dialing 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.

Examples

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

http://client.txtnation.com/client_scripts/hlr/nlookup.zip

 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.