MNP HTTP API v2.0

1. Document overview

This document provides a specification of the MNP HTTP Query Service

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

Queries need to be sent using HTTP or HTTPS (TLS v:1.2) protocol to URL:

 http://mnp1.horisen.com:16091/mnpjson
 https://mnp1.horisen.com:16089/mnpjson

Query parameters can be sent as GET.

Customer sends query with following parameters:

Name Default value Description Example
msisdn - MSISDN international format with or without leading'+' +41787078880
user - Account username testuser
password - Account password testpass
opinfo (Boolean) - This parameter is optional -

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 error code 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"
    }
}

3.3 Submission examples

This example sends MNP Query for:

  • account testuser with its password
  • for MSISDN 41787078880
https://mnp1.horisen.com:16089/mnpjson?msisdn=41787078880&user=testuser&password=testpass

To get extended HTTP response with country and operator use the following example:

https://mnp1.horisen.com:16089/mnpjson?msisdn=41787078880&user=testuser&password=testpass&opinfo=true

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

3.4 Receiving MNP Query results

Response example:

{
    "imm":
    {
        "qid": "64db658740ffddcc802abb7abce78cc2",
        "msisdn": "85268973862",
        "mcc": "454",
        "mnc": "00",
        "country": "Hong Kong",
        "operator": "Hong Kong Telecommunications (HKT) Limited",
        "errcode": "000",
        "ported": "No",
        "roaming": "No",
        "valid": "Yes",
        "online": "No"
    }
}

Fields in response:

Name Description Example
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
ported Available values: No, Yes, Unknown -
roaming Available values: No, Yes, Unknown -
valid Available values: No, Yes or Unknown -
online Available values: No, Yes or Unknown -
country Added if opcode is used with value "true" -
operator Added if opcode is used with value "true" -

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 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_NOROUTE 142 Destination is not allowed for this 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

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