MNP HTTP API v1.0 (deprecated)
1. Document overview
1.1 Scope
Scope of this document is to provide specification of the HTTP MNP Query Service.
1.2 Target audience
This is an internal HORISEN document that serves as technical guidelines for implementing the 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 indicates which mobile operator (identified by MCC/MNC) is handling the given subscriber MSISDN. There may be MSISDNs that are not active but still belong to a 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 enable the service, HORISEN will create the following data for the customer:
- Customer ID
- Username for MNP Query account
- Password for MNP Query account
The customer needs to provide the following data:
- 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. The query result is returned in the content of the HTTP response.
3.2 Sending MNP query
Queries must be sent using HTTP/HTTPS 1.0 protocol to the following 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 in 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:
- HTTP Status code 2xx
- 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 when the response is provided in a reliable way. RC_UNRELIABLE is returned when the response cannot be provided reliably (MNP data source is not working) but MCC/MNC pair is discovered by checking Mobile Operator prefix database.
If the query couldn't be processed:
- HTTP Status code 4xx or 5xx
- 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 an example of parameter representing an internal reference ID on the 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 the network where the number is ported. | 03 |
| ERRCODE | Error code, see 4. How to handle errors. | 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 given username/password. |
| RC_IP_NOT_ALLOWED | 104 | Sending from client's IP address is 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) is 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. |
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 a result is received on the result URL, check the error field (%e) first. If it is not 000, ignore the MCC (%c) and the MNC (%n) information.