MNP HTTP API v1.0 (deprecated)

1. Document overview

1.1 Scope

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

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

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

HTTP MNP API is used on Customer side. It allows any MNP customers to connect to HORISEN MNP Platform to discover MNP (Mobile Number Portability) information about given MSISDN.

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

3.1 Querying MNP/HLR information

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

3.2 Sending MNP query

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

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

Query parameters can be sent as GET.

Customer sends query with following parameters:

Name Default value Description Example
msisdn - MSISDN ininternational formatwith 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:
IMM QID:135c5eea40008a01807c7229938dd852 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 coudn't be provided in reliable way (MNP data source is not working) but MCC/MNC pair is discovered by checking Mobile Operator prefix database.

If query coudn't be processed:

  1. HTTP Status code 4xx or 5xx
  2. If possible, content: ERR <error code> <error message>

Example:

ERR 113 No credit on account balance

3.3 Submission examples

This example sends MNP Query for:

  • account testuser with its password
  • for MSISDN 41787078880
  • refid is given here as an example of parameter that is internal reference ID on Customer's system. It's fully optional and there can be more then one such parameters.
https://sms.horisen.info:12015/mnp?msisdn=41787078880&user=testuser&password=testpass

As shown in example, all HTTP parameters need to be URL encoded.

3.4 Receiving MNP Query results

Response begins with IMM. Example:

IMM QID:135c5eea40008a01807c7229938dd852 MCC:228 MNC:03 ERRCODE:000 ERRDESC:

Fields in response:

Name Description Example
QID Query ID 135c5eea40008a01807c7229938dd852
MCC MCC 228
MNC MNC of network where number isported 03
ERRCODE Error code, see ยง4 140
ERRDESC Error Description No information about given MSISDN

In case of success,

Error code Value Description
RC_OK 000 OK, no error
RC_APPLICATION_ERROR 101 Internal application error
RC_NO_ACCOUNT 103 No account with givenusername/password
RC_IP_NOT_ALLOWED 104 Sending from client's IP addressnot 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 iswrong
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 beprovided, but MSISDN is checked against prefix database and MCC/MNC is provided based on prefix.

4. How to handle errors

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

ERR 113 No credit on account balance

When result is received on result-url check first error field (%e) and if it's not 000 ignore mcc (%c) and mnc (%n) information.