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 the opinfo parameter is used with value "true".	-
operator	Added if the opinfo parameter 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	A reliable response could not be provided, but the MSISDN is checked against the prefix database and MCC/MNC is provided based on the 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 the result is received on the result URL, check the error field first and if it's not 000, ignore MCC and MNC information.