HTTP MNP Protocol » V2.0 (01.12.2016)

Document overview

Scope

Scope of this document is to provide specification of HTTP MNP Query Service.

Target audience

This is internal HORISEN document to serve as technical guidelines for implementing HTTP MNP Query Service. When service becomes production stable target audience will be Customers.

Service overview

HORISEN MNP Service helps customers to discover MNP (Mobile Number Portability) information about given MSISDN. MNP information is about which mobile operator (identified by MCC/MNC) is handling given subscriber MSISDN. There may be MSISDNs that are not active but still belonging to some mobile operator.

Customer Account creation

In order to have service enabled, HORISEN will create following data for customer:

  1. Customer ID
  2. Username for MNP Query account
  3. Password for MNP Query account

Customer needs to provide following data:

  1. Set of IP addresses from which queries will be sent

Querying MNP/HLR information

MNP/HLR information can be queried using synchronous method. Query result is returned back in content of HTTP response.

Sending MNP query

Queries need to be sent using HTTP/HTTPS 1.0 protocol to URL:

http://sms.horisen.info:12015/mnpjson

Query parameters can be sent as GET.

Customer sends query with following parameters:

NameDefault valueDescriptionExample
msisdn - MSISDN international format with or without leading'+' +41787078880
user - Account username testuser
password - Account password testpass

If query is accepted server will return in HTTP response:

  1. HTTP Status code 2xx
  2. Content:

in JSON format:

{
	"imm": {
		"qid" : "135c5eea40008a01807c7229938dd852",
		"msisdn": "41787078880",
		"mcc" : "228",
		"mnc" : "03",
		"errcode" : "000",
		"errdesc" : ""
	}
}

Field errcode may be RC_OK(000) or RC_UNRELIABLE(151). Response RC_OK is returned in case that response is provided in reliable way. RC_ UNRELIABLE is returned when response couldn't be provided in reliable way (MNP data source is not working) and MCC/MNC pair is discovered by analyzing operator prefix database.

If query couldn't be processed:

  1. HTTP Status code 4xx or 5xx
  2. If possible, content:

in JSON format:

{
	"error": {
        "errcode": "113",
		"errdesc": "No credit on account balance"
	}
}

Submission examples

This example sends MNP Query for:

  • account testuser with its password
  • for MSISDN 41787078880
https://sms.horisen.info:12015/mnpjson?msisdn=41787078880&user=testuser&password=testpass

As shown in the example, all HTTP parameters must be URL encoded.

Receiving MNP Query results

Response example:

{
	 "imm": {
		"qid": "db57418240871fab80233adc51689ac8",
		 "msisdn": "41787078880",
		 "mcc": "228",
		 "mnc": "02",
		 "errcode": "000",
		 "errdesc": ""
	 }
}

Fields in response:

NameDescriptionExample
qid Query ID 135c5eea40008a01807c7229938dd852
msisdn MSISDN international format with or without leading'+' 41787078880
mcc MCC 228
mnc MNC of network where number is ported 03
errcode Error code, see list of error codes below 140
errdesc Error Description No information about given MSISDN

In case of success,

Error codeValueDescription
RC_OK 000 OK, no error
RC_APPLICATION_ERROR 101 Internal application error
RC_NO_ACCOUNT 103 No account with given username/password
RC_IP_NOT_ALLOWED 104 Sending from client's IP address not allowed
RC_MISSING_MANDATORY_PARAMETER 110 Some mandatory parameter is missing
RC_UNKNOWN_QUERY_TYPE 111 Unknown query type (typeparameter)
RC_BAD_PARAMETER_VALUE 112 Format of some parameter is wrong
RC_NO_CREDIT 113 No credit on account balance
RC_NOMSISDNINFO 140 No information about MSISDN.
RC_NOMSISDNDEST 141 No information about selected destination (country) available for Customer's account
RC_UNRELIABLE 151 Reliable response couldn't be provided, but MSISDN is checked against prefix database and MCC/MNC is provided based on prefix.

How to handle errors

If HTTP status is 420 (METHOD_INVOCATION_FAILURE) check error code returned in HTTP response:

{
	"error": {
		"errcode": "113",
		"errdesc": "No credit on account balance"
	}
}

When result is received on result-url check first error field and if it's not 000 ignore mcc and mnc information.