How to use the service

IMPORTANT INFORMATION

Contents
1 Introduction
2 IMPORTANT INFORMATION
3 What can you do?
4 Requirements
5 Technologies
6 Security
7 Detailed Communication Process
7.1 Synchronous GET Requests
7.2 Parameters
7.3 Return Values
7.4 Return Values: An Explanation
7.5 Other Return Values: An Explanation
7.6 Premium Return Values
7.7 VLR Lookup
7.8 Troubleshooting
8 Examples

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

Requirements

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

The sending of an HTTP request that transports the lookup to GSM BILLING’s platform.
Optionally, for asynchronous lookups, a service must be embedded into the client’s web server to process delivery reports sent by GSM BILLING.
Technologies

GSM BILLING’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 GSM BILLING.
Security

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

Where possible, GSM BILLING 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.

URLs:
For HTTP GET requests:

http://gsmairtime.co.uk/test/hlr.php

Parameters
The parameters that you should send through to manipulate the output of GSM BILLING’s Number Lookup platform are listed below:

Name Required? Comments
user Yes The username provided to you by GSM BILLING
password Yes The password provided to you by GSM BILLING
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.

Example : http://gsmairtime.co.uk/test/hlr.php?user=yourusername&password=yourpassword&msisdn=4477666666666&return=json

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:4477666666666 status=”ok” mcc=”234″ mnc=”02″ operatorname=”Telefónica O2 UK Ltd” isoalpha3code=”GBR” END:4477666666666–

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:4477666666666
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.
mnc=”02″
The Mobile Network Code that determines which network the subscriber belongs to.
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.
–END:4477666666666
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:
{
4477666666666: {

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.

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 GSM BILLING can be any of the following types: 4477666666666, +4477666666666, 004477666666666 (where 44 or 0044 is the international dial code for the United Kingdom). GSM BILLING’s preference is an MSISDN in the format: 4477666666666.

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