This document describes the SPIRIlookup HTTP GET Interface. It gives the basics of how to use the API and provides a list of available parameters. The document is intended for application developers and/or integrators. Basic knowledge of the HTTP protocol is assumed.
HTTP GET interface
Lookup the current mobile phone operator for a Swedish mobile phone number. Lookup is performed in a local database that contains number portability information provided by Swedish Number Portability Administrative Center. The returned information is never older than 48 hours.
Lookup subscriber status and IMSI from the Home Location Register (HLR) with a live SRI for SM request sent over the SS7 network to the HLR handling the subscriber for the provided MSISDN. A SRI for SM request typically need between 0.3 and 0.8 seconds to execute.
Combines the information from both Sweden and Basic in a single request. Access to database lookup and HLR lookup is granted separately.
Two different accesspoints are available. One in Stockholm and another in Karlskrona. Regardless of which accesspoint that is being used each new connection is load balanced over the same set of available backend servers. The reason for providing two different accesspoints is to provide an alternative if one of the sites will experience a power failure or suffer from DDOS attack. The two accesspoints are:
You can also omit the number and send requests to
get-spirilookup.spiricom.spirius.com, but note that this DNS entry
is identical to
get1-spirilookup.spiricom.spirius.com and does not provide any failover functionality.
The requests are secured by HTTPS and authenticated using Basic Authentication as defined in RFC 2617 (Credentials are encoded in the Authorization request-header field).
To send a request you send a REST-style URI containing the API version, service and
https://get1-spirilookup.spiricom.spirius.com:54011/v1/lookup/sweden/46712345678 If you enter a request from a
web browser you will be prompted for credentials by a popup dialog.
The response will be json-encoded and contain different fields depending on which service that is requested. Sample
response from an advanced lookup request (i.e. containing all fields) for number
1 2 3 4 5 6 7 8 9 10 11 12 13 14
Should there be anything wrong with the request, it will be rejected with an HTTP error indicating the nature of the problem, please see section of Response codes below.
HTTP error codes
||OK||Request was received and processed.|
||Bad request||Invalid MSISDN.|
||Unauthorized||Wrong user or password, or user lacks access rights for SPIRIlookup. It could also be that the account is inactive if the contract has been terminated.|
||Forbidden||User lacks access right to requested service.|
||Service unavailable||The server is currently unable to handle the request due to a temporary overload or maintenance of the server.|
Response codes for Sweden service
|0||The request was successful. For a mobile network operator, MNC and Operator name are given in the response. For a MVNO the first part of IMSI is present in the response instead of MNC (as MVNO don’t have MNC).|
|11||Mandatory parameter MSISDN is not a valid Swedish phone number.|
|16||Given MSISDN is not a mobile phone number; it could be a geographical (land line) number.|
Response codes for Basic and Advanced services
For Advanced service, an error from the SRI for SM request take precedence over an error from the Sweden service.
||OK||The request was successful. First part of IMSI is present in the response.|
||SYSTEM_FAILURE||The HLR responded to the SRI for SM request with an error indicating that a system failure occurred in the HLR while processing the request.|
||DATA_MISSING||The HLR responded to the SRI for SM request with an error indicating the data was missing.|
||FACILITY_NOT_SUPPORTED||The HLR responded to the SRI for SM request with an error indicating that short message facility is not supported.|
||UNKNOWN_SUBSCRIBER||The HLR responded to the SRI for SM request with an error indicating there is no subscriber for the given MSISDN.|
||TELE_SERVICE_NOT_PROVISIONED||The HLR responded with an error indicating that SMS teleservice is not provisioned for the subscriber.|
||CALL_BARRED||The HLR responded to the SRI for SM request with an error indicating the SMS service is barred for the subscriber.|
||ABSENT_SUBSCRIBER_SIM||The HLR responded to the SRI for SM request with an error indicating the subscriber is not connected to the network.|
||HLR_ABORT||The HLR (or some other entity in the network) aborted the SRI for SM request.|
||HLR_LOCAL_CANCEL||No response for the SRI for SM request was received.|
||TIMEOUT||No response for the SRI for SM request was received.|
||HLR_REJECT||The HLR rejected the SRI for SM request.|