Discovery REST API Overview

The Discovery Service provides the developer with details of the home operator that serves the end user. Once you obtain the details for a specific user you can perform the Mobile Connect API calls to authorise that user.

Every mobile operator has a Mobile Country Code (MCC) and Mobile Network Code (MNC) to identify themselves. The Discovery service will identify the MCC_MNC and return the details, along with the relevant operator's Mobile Connect API details, to an application. This enables the application to call the relevant Mobile Connect service.

The Discovery service has various methods of obtaining the MCC_MNC. Where possible, this is done in the background, but in some situations the mobile number is required from the user. Here, the Discovery service will present an "Operator Selection User Interface" prompting the end user to enter their MSISDN.

Discovery Operator Selection User Interface

The Operator Selection User Interface, is a web-based application service provided by the Discovery API that determines the home operator of your user.

Multilanguage support is available and the number of supported languages continuing to increase.

The Operator Selection User Interface URL is obtained via the Discovery API request (please refer to the example at the end of the page). The URL is protected with a unique session_id. If an invalid session_id is provided, an error will be displayed instead of the Operator Selection User Interface.

Upon a successful lookup, the serving operator's Mobile Country Code and Mobile Network Code (in MNC_MCC format) will be redirected to your Redirect_URL (please refer to the example at the end of the page).

The Operator Selection User Interface is also able to automatically recognise the serving operator if the user is accessing your service via a Mobile Data Network

This functionality is only available when an operator has implemented this feature. In this case the operator may have injected custom HTTP headers in the requests or the operator has notified Discovery Services of the range of IP addresses that they own. With this extra information, the Operator Selection User Interface can provide you with the user's home operator directly.

Discovery API use cases

  • A user is accessing your service from a web browser/tablet where you cannot get the MCC/MNC directly.

    To obtain the user's MCC/MNC, forward the user to the Operator Selection User Interface. This allows the user to enter their MSISDN and the correct MCC/MNC will be identified and returned to you. With this information you will be able to invoke the Discovery API to obtain the details required to perform the Mobile Connect authorisation process.

  • A user accessing your service from a Smartphone Mobile Application where your application is able to retrieve the MCC_MNC from the SIM.

    After obtaining the MCC/MNC from the SIM, you can invoke the Discovery API to obtain the details required to perform the Mobile Connect authorisation process.

  • A user accessing your service from a web browser/tablet where you know their MSISDN.

    Invoke Discovery API with the MSISDN to obtain the details required to perform the Mobile Connect authorisation process.

Discovery API Reference

Request

GET {Provider}/v2/discovery/?query_parameters

POST {Provider}/v2/discovery/

Header parameters

Parameter name Value Description
Mandatory parameters
Authorization string HTTP Basic authorization to access the API. Base64 encoded String of your "<client_id>:<client_secret>"
Optional parameters
Accept string Indicates the content type required for the response. Only applies to request with OperatorSelection Response. For all other requests, always default to "application/json"

Accepted Values:

  • application/json
  • text/html

(Default: text/html)

Accept-Language string Indicates the language preference of the Operator Selection Web App. Not all languages are currently supported. Language support will be added on an ongoing effort.

Accepted Values.

  • en (English)
  • es (Spanish)

(Default: en)

Query parameters

Parameter name Value Method Description
Mandatory parameters
Redirect_URL string POST
GET
The Redirect URL that you set when you create your Application that determines where Discovery Service sends responses to your OperatorSelection request.
Optional parameters
Identified-MCC string POST
GET
3 Digit Numeric "Mobile Country Code" of the device SIM Card obtained via Native application.
Identified-MNC string POST
GET
2 Digit Numeric "Mobile Network Code" of the device SIM Card obtained via Native application.
Selected-MCC string POST
GET
3 Digit Numeric "Mobile Country Code" of the response from the OperatorSelection WebApp.
Selected-MNC string POST
GET
2 Digit Numeric "Mobile Network Code" of the response from the OperatorSelection WebApp.
Using-Mobile-Data boolean POST
GET
Set to "true" if your application is able to determine that the user is accessing the service via mobile data. This tells Discovery Service to discover using the mobile-network.

(Default: true)

MSISDN string POST The mobile number in E.164 number formatting of your user if you already obtained their number in the past.

Response

There are multiple type of response depending on the request.

1. Request with HTTP header accept: application/json and with no information of MCC/MNC or MSISDN.

  {
    "links": [
      {
        "rel": String,
        "href": String
      }
    ]
  }
Name Value Description Example
links[] list collection of available links  
links[].rel string The relationship of the links object operatorSelection
links[].href string The full url to the links object {provider}/v2/discovery/users/operator-selection ?session_id=tcsjbd1vhoe9gu0j8ev6mhrj3a7q

 

2. Request with HTTP header accept: */* and with no information of MCC/MNC or MSISDN

< HTTP/1.1 302 Found
< X-Powered-By: Express
< Location: {provider}/v2/discovery/users/operator-selection?session_id=tlopdkihp2xa9d9...a6hfxhljfnfla3vxyep
< Vary: Accept
< Content-Length: 0
< Date: Wed, 17 06 2015 12:31:46 GMT
< Vary: Origin
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers:
< Access-Control-Max-Age: 3628800
< Access-Control-Allow-Methods: GET, POST, OPTIONS
< Access-Control-Allow-Credentials: true
< X-Powered-By: Apigee
< Connection: keep-alive
<

 

3. Response from OperatorSelection User Interface

< HTTP/1.1 302 Found
< X-Powered-By: Express
< Location: {Redirect_URL}?mcc_mnc=001_01&subscriber_id=kjiohkdasnuihlawhsdnahkajsdbap
< Vary: Accept
< Content-Length: 0
< Date: Wed, 17 06 2015 12:31:46 GMT
< Vary: Origin
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers:
< Access-Control-Max-Age: 3628800
< Access-Control-Allow-Methods: GET, POST, OPTIONS
< Access-Control-Allow-Credentials: true
< X-Powered-By: Apigee
< Connection: keep-alive
<

4. Request with a valid information of MCC/MNC or MSISDN.

{
  "ttl": timestamp,
  "response": {
    "client_id": String,
    "client_secret": String,
    "serving_operator": String,
    "country": String,
    "currency": String,
    "apis": {
      "operatorid": {
         "link": [
          {
            "href": String,
            "rel": String
          }
        ]
      }
    }
  },
  "subscriber_id": String;
}
Name Value Description Example
ttl timestamp "time to live", the expiry timestamp when this discovery details is nolonger valid. 1439736409839
response object Details of the serving operator that you will require to perform API requests to.  
client_id string client_id part of your credential to be used by OIDC requests 09jad3WMxMmRjMWUwNjA3Yzf90sc
client_secret string client_secret part of your credential to be used by OIDC requests isM0ZDRlN2FiNDcwYTI3NzM
serving_operator string Name of this serving operator telefonica_spain, digi, telenor_norway, swisscom_switzerland, dialog_srilanka, ooredoo_qatar, ..
country string Country name of this serving operator Spain, Malaysia, Norway, Switzerland, Sri Lanka, Qatar, ..
currency string Currency of this serving operator euro, RM, NOK, SwissFranc, Rupee, QAR, ..
apis object Available API from the serving operator  
operatorid object Operator Identity API  
link[] list collection of available links  
link[].href string The relationship of the links object authorization, token, userinfo
link[].rel string The full url to the links object  
subscriber_id string MSISDN value encoded with operator RSA certificate that can be passed along as "login_hint" parameter of the Mobile Connect API. (only available when request is contains MSISDN) ce2898c6c38b47710. . . . .5f8f3217ddd95d2ae91c53733a3bc