HLR Number Lookup API
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
- 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.
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.
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:
|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|
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:
operatorname="Telefónica O2 UK Ltd"
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:
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.
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.
The Mobile Country Code that the subscriber belongs to (see http://en.wikipedia.org/wiki/ Mobile_Country_Code).
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.
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).
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.
The IMSI number of the mobile subscriber. (RTLU only)
Whether the handset is currently powered on. Values can be "on" or "off". (RTLU only)
||The request was successful|
||The data was missing|
||The subscriber is unknown|
||The service is restricted by the destination network|
||The subscriber is absent|
||An unexpected data value in the request|
||A system failure occurred in the HLR|
||Short message facility is not supported|
||SMS teleservice is not provisioned|
||The HLR request was rejected|
|| The HLR (or some other entity) aborted the request. No |
response to the request was received
||No response for the HLR request was received.|
||No response to the request was received|
||Maximum ongoing requests exceeded|
||Request is blocked|
||Some mandatory parameter are missing in the request|
||The number are not allowed on this service|
||Wrong format of the MSISDN parameter|
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.
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.