Interface Description

Introduction

Scope

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

Service levels

Sweden

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.

Basic

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.

Advanced

Combines the information from both Sweden and Basic in a single request. Access to database lookup and HLR lookup is granted separately.

Access points

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:

• https://get1-spirilookup.spiricom.spirius.com:54011
• https://get2-spirilookup.spiricom.spirius.com:54011

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.

Request syntax

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

Response syntax

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 +46712345678:

 HTTP/1.1 200 OK Content-Type: application/json Content-Type: text/plain;
charset=utf-8 {
  "CC": "", "Country": "", "HLR": "HLR_LOCAL_CANCEL", "IMSI": "", "MCC": "", "MNC": "", "Operator": "", "R": 200, "SPID": "" 
}

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

Code	Response	Description
200	OK	Request was received and processed.
400	Bad request	Invalid MSISDN.
401	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.
403	Forbidden	User lacks access right to requested service.
503	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

Response code	Description
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.

Response code	Response	Description
0	OK	The request was successful. First part of IMSI is present in the response.
100	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.
101	DATA_MISSING	The HLR responded to the SRI for SM request with an error indicating the data was missing.
103	FACILITY_NOT_SUPPORTED	The HLR responded to the SRI for SM request with an error indicating that short message facility is not supported.
104	UNKNOWN_SUBSCRIBER	The HLR responded to the SRI for SM request with an error indicating there is no subscriber for the given MSISDN.
105	TELE_SERVICE_NOT_PROVISIONED	The HLR responded with an error indicating that SMS teleservice is not provisioned for the subscriber.
106	CALL_BARRED	The HLR responded to the SRI for SM request with an error indicating the SMS service is barred for the subscriber.
107	ABSENT_SUBSCRIBER_SIM	The HLR responded to the SRI for SM request with an error indicating the subscriber is not connected to the network.
200	HLR_ABORT	The HLR (or some other entity in the network) aborted the SRI for SM request.
200	HLR_LOCAL_CANCEL	No response for the SRI for SM request was received.
299	TIMEOUT	No response for the SRI for SM request was received.
999	HLR_REJECT	The HLR rejected the SRI for SM request.