Skip to content

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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.