HLR Lookup Api V 3.4 PDF
HLR Lookup Api V 3.4 PDF
com
TABLE OF CONTENTS
INTRODUCTION ........................................................................................................................................................................ 2
HTTP PROTOCOL ....................................................................................................................................................................... 3
HLR LOOKUP WITH THE HTTP API REQUEST .............................................................................................................................. 4
EXAMPLES FOR HLR LOOKUP .................................................................................................................................................... 6
CREDIT BALANCE ...................................................................................................................................................................... 7
APPENDIX ................................................................................................................................................................................. 8
INTRODUCTION
With the advent of number portability, it is becoming increasingly difficult to reliably identify in which
network a mobile number belongs to, just by checking the number (MSISDN).
The HLR lookup (referred also as Mobile Network Query or IMSI lookup or MSISDN lookup or Mobile
Number Portability lookup service) allows you to check in real-time, whether a mobile number is valid,
which network it belongs to, if it is roaming and also its location.
HLR or Home Location Register is a central database containing details for each mobile phone subscriber
that is authorized to use the GSM core network. IMSI or International Mobile Subscriber Identity is a
unique number associated with all GSM networks and mobile phone users. This unique number is stored
inside the mobile phone SIM card. The used network identifies each mobile phone subscriber by this
particular number. The IMSI provides information such as location of handset, user preferences and
account status.
When you submit a MSISDN (mobile number) to our HLR lookup service, our system checks whether the
mobile number is valid. If so, it returns the IMSI, the operator name and the country plus the MCC/MNC
(Mobile Country Code/Mobile Network Code) associated with it.
This service can help mobile marketers identify and eliminate invalid numbers and SMS aggregators or
resellers optimize their SMS routing. By using this service you avoid having message delivery failureres
due to portability or old numbers in databases. Specifically:
• Simple Users - determine if the number is in use since many people discontinue their mobile
contracts frequently
• Marketers - clean up your databases and delete the invalid numbers
• Application providers and developers - send relevant information to mobile users based on
location
• Organizations wanting to deliver secure services - validate the identity of the mobile user
• Operators, aggregators and service providers - avoid paying high/unexpected interworking fees,
route through the least cost provider and keep your customers happy by ensuring all messages get
routed well
This document describes MobiWeb’s HTTP HLR Lookup API platform. It is used either via HTTP POST or
GET requests. It can be used directly or through any programming language allowing developers and
users to interface their system easily with MobiWeb’s HLR services.
HTTP PROTOCOL
The Hypertext Transfer Protocol (HTTP) is the most common networking protocol used by all Web
applications. HTTP is the foundation of data communication for the World Wide Web. It is based on
requests for resources made with URLs and responses to them. The requests are made by clients (e.g.
Web Browsers) and the responses are delivered by Servers (e.g. Website). Below you can find some basic
terminology of the HTTP Protocol:
URL: A Uniform Resource Locator specifies where an identified resource is available and the mechanism
for retrieving it. That is the address of the resource.
e.g. http://www.domain.com/test.html
Here the URL is ‘http://www.domain.com/test.html’
Parameters: The parameters supplied to the URL. These begin at the end of the resource with the
character ‘?’ and are separated by character ‘&’.
e.g. http://www.domain.com/test.html?paramA=1¶mB=testvalue
Here the parameters are paramA with the value of ‘1’ and paramB with the value of ‘testvalue’.
In a UNIX shell you can execute the following command (if libcurl is installed):
e.g. curl ‘http://www.domain.com/test.html’
In a UNIX shell you can execute the following command (if lynx is installed):
e.g. lynx -dump ‘http://www.domain.com/test.html’
To send an HTTP HLR Lookup request you must provide the correct URL with the required parameters. An
example HTTP GET request follows:
http://IPADDRESS/bulksms/doHLR.go?username=userXXXX&password=passXXXX&phone=20xxxxxxxxxx
Note: IPADDRESS, username and password are provided to users from respective Account Manager by
email.
All HTTP HLR Lookup Requests return the Status Code, MCC, MNC and Location of the requested mobile
number or an Error Code with the relevant advanced status code information. (Please refer to Table 2 and
Table 3 for returned values and Error Code explanations respectively)
e.g. 1|602|1|202234250000|602014531155 - Valid Mobile (Status 1) from country Egypt (MCC 602) that
belongs to Operator Mobinil (MNC 1) . Device is located at MSC address 202234250000. Subscriber’s
International Mobile Subscriber Identity (IMSI) is 602014531155. (Please refer to Appendix A – Mobile
Network Operators Reference for worldwide MCC MNC codes)
Returned Values
Returned Value Value Description
Status Code 0 Invalid Mobile Number
1 Valid Mobile Number
ERROR Internal Error. Try later (HLR not charged)
MCC XXX The Mobile Country Code of the mobile
number.
MNC XXX The Mobile Network Code of the mobile
number.
Location XXXXXXXXXXXX The current location (MSC address) of the
(MSC Address) subscriber.
For specific networks/countries that
information might not be available. If for any
reason there is no location information 0 is
returned.
IMSI XXXXXXXXXXXX International Mobile Subscriber Identity:
Unique identification number of subscriber.
For specific networks/countries that
information might not be available. If for any
reason the IMSI is not available, 0 is returned.
Advanced ABSENT_SUBSCRIBER_SM The subscriber is absent.
Status Code DATA_MISSING The data is missing.
(supplied only TELE_SERVICE_NOT_PROVISIONED The SMS teleservice is not provisioned.
when status UNEXPECTED_DATA_VALUE An unexpected data value was found in the
code is zero) request.
SYSTEM_FAILURE A system failure occurred.
FACILITY_NOT_SUPPORTED The short message facility is not supported.
CALL_BARRED The HLR is barred by the queried operator.
HLR_ABORT Operator’s HLR blocked the HLR request.
HLR_REJECT Operator’s HLR rejected the request.
HLR_LOCAL_CANCEL Operator’s HLR did not respond to the
request.
UNKNOWN_SUBSCRIBER The subscriber is unkown.
TIMEOUT HLR request received not response.
Table 2 – HLR Lookup Returned Values
Error Codes
ERROR # Description
ERROR100 Temporary Internal Server Error. Try again later
ERROR101 Not valid parameters in request
ERROR102 No credits available
Table 3 – HLR Lookup Error Codes
Returns the Status Code, MCC, MNC and Location of the requested mobile number or an Error Code
with the relevant advanced status code information. (Refer to Table 2 and Table 3 for returned values
and Error Code explanations respectively)
e.g. 1|602|1|202234250000|602014531155 – Valid
e.g. 0|000|00|00|00|ABSENT_SUBSCRIBER_SM – Invalid because subscriber is absent (handset off etc.)
e.g. 0|000|00|00|00|UNKNOWN_SUBSCRIBER – Invalid because subscriber is invalid
e.g. ERROR|000|00|00|00|RETRY_LATER – There was an internal error and HLR must be retried (and
not charged)
phone=20xxxxxxxxxx
showdetails=1
Returns the Status Code, MCC, MNC and Location of the requested mobile number or an Error Code
with the relevant advanced status code information. (Refer to Table 2 and Table 3 for returned values
and Error Code explanations respectively)
e.g.
COUNTRY: Egypt(+20)
MCC: 602
MNC: 1
LOCATION: 202234250000
IMSI: 602014531155
OPERATOR: Mobinil
CREDIT BALANCE
An HTTP API request is available for users who wish to retrieve the remaining credits of their accounts. An
example of HTTP GET request is:
http://IPADDRESS/bulksms/getBALANCE.go?username=userXXXX&password=passXXXX&type=HLR
An HTTP API Credit Balance request returns the number of available EUROS of the user’s account.
e.g. 945.35 €
APPENDIX
Puerto Rico Puerto Rico Telephone Company (Claro GSM / Verizon) 330 12
Puerto Rico Sprint Spectrum 330 20
Puerto Rico T-Mobile Puerto Rico 330 490
Qatar Q-Tel 427 1
Qatar Vodafone Qatar 427 2
Reunion Orange Reunion 647 0
Reunion Outremer Telecom Reunion 647 2
Reunion Societe Reunionnaise du Radiotelephone 647 10
Romania Cosmote Romania Mobile Telecommunications 226 3
Romania Digi.mobil 226 5
Romania Orange Romania 226 10
Romania Vodafone Romania 226 1
Romania Zapp Mobile 226 4
Russian Federation Baykalwestcom 250 12
Russian Federation Don Telecom (MTS) 250 10
Russian Federation Ekaterinburg 2000 (MOTIV) 250 35
Russian Federation Ermak RMS /UTEL(JSC Uralsvyazinform) 250 17
Russian Federation Extel 250 28
Russian Federation Kuban-GSM 250 13
Russian Federation Mobicom Novosibirsk 250 23
Russian Federation Mobile Communication System - Povolzhie 250 2
Russian Federation Mobile TeleSystems 250 1
Russian Federation New Telephone Company 250 16
Russian Federation Nizhegorodskaya Cellular Communications 250 3
Russian Federation Orensot 250 11
Russian Federation Primtelefon 250 92
Russian Federation Siberian Cellular Communications 250 5
Russian Federation SMARTS 250 7
Russian Federation StavTeleSot 250 44
Russian Federation Tele2 Russian Federation 250 20
Russian Federation Uralsvyazinform 250 39
Russian Federation VimpelCom 250 99
Russian Federation Volgograd Mobile 250 19
Rwanda MTN Rwanda 635 10
Rwanda Rwandatel 635 12
Saint Lucia Cable & Wireless (St. Lucia) 358 110
Saint Lucia Digicel (St Lucia) Limited 358 50
Samoa Digicel Samoa 549 1
Samoa SamoaTel 549 27
San Marino Telecom Italia San Marino 292 1
Sao Tome and Principe Companhia Santomese de Telecomunicacoes (CST) 626 1
Saudi Arabia Etihad Etisalat Company (Mobily) 420 3
Saudi Arabia Saudi Telecom Company (STC) 420 1
Saudi Arabia ZAIN Saudi Arabia 420 4
Senegal Expresso Senegal 608 3
Senegal Sonatel 608 1
Senegal Tigo (Sentel) 608 2
Serbia Telekom Srbija a.d. 220 3
ABOUT MOBIWEB
Using direct connections with telecommunication carriers and operators in the largest cloud data centers
spanning over 4 continents, MobiWeb provides high quality communication solutions to billions of subscribers
in 229 countries. MobiWeb is backed up by a second to none technical team.
Driven by excellence MobiWeb has already established a strong customer base in Europe, Latin America, Africa
and Asia through the provision of telecommunication solutions.
Playing an important role at the telecom and marketing industry, MobiWeb is an associate member of the
GSMA Association and a member of the Mobile Marketing Association.
MobiWeb Group
Hong Kong USA UK Brazil Turkey Greece Cyprus Chile Romania Belize