MNP HTTP Supplier API v1.0
1. Introduction
1.1 API Description
HORISEN HTTP API provides an efficient way to retrieve MCC and MNC information of recipient mobile subscriber by sending querying to MNP Supplier.
This document describes necessary parameters and samples to demonstrate users how to use the HORISEN MNP Supplier HTTP API.
2. Topics
2.1 Authentication
All API calls require authentication. This is essential for the API to identify which user is making the call so that appropriate results will be returned, as well as for security reasons.
For this purpose, API uses basic authentication. Authentication data are sent via HTTP header "Authorization".
Steps to construct authorization header:
- Base64 encode the API Key.
- Supply an "Authorization" header with content "Basic" followed by the encoded API Key.
Example:
Authorization = "Basic Base64(APIKey)"
Request an API Key from our support team. Please keep your API Key safe to prevent any unauthorized access. Once you obtain your API Key, you will have to use it in every API call you make.
2.2 Versioning
HTTP API will support versioning through URI Path
Example:
- Version 1: https://{your mnp api server domain name}/horisen-mnp/v1
- Version 2: https://{your mnp api server domain name}/horisen-mnp/v2
Please keep in mind that currently only V1 is supported.
2.3 MNP request over HTTP API interface
Description
Using this method, you can retrieve information on specific phone number
Base URL: https://{your mnp api server domain name}/v1
HTTP Request Type: GET
Service Endpoint: /number-lookup/msisdn={msisdn}
Content Type: application/json
Parameters
msisdn - String (Required), MSISDN number in international format E.164
https://mnp.example.com/horisen-mnp/v1/number-lookup?msisdn=525614157575
Successful Responses
{
"errorcode": 0,
"errordesc": "OK",
"number": "525614157575",
"ported": true,
"mcc": "334",
"mnc": "20",
"country": "Mexico",
"operator": "TELCEL",
"numbertype", "mobile"
}
Description of successful JSON response:
- errorcode - Integer (Required) - result code, 0 for OK (please see paragraph 6: HTTP API Codes)
- errordesc - String (Required) - status message "OK – number successfully resolved"
- number - String (Required) - number
- ported - Boolean (Required) - "true" means ported at least once, "false" means no porting record and queried number still belongs to original operator
- mcc - String (Required)
- mnc - String (Required)
- country - String
- operator – String
- numbertype – String (mobile/fix/wireless/voip/m2m/satellite)
Unsuccessful Response:
{
"errorcode": 0,
"errordesc": "OK"
}
Description of unsuccessful JSON response:
- errorcode - Integer (Required) - error code (please see paragraph 6: HTTP API Codes)
- errordesc - String (Required) - error message
2.4 HTTP Status codes
Every HTTP response has a status code sent back by the MNP Supplier server to define how the HORISEN MNP API has handled the response. The most common statuses you may have encountered are 200 OK and 404 Not Found. Check out the list of the HTTP status codes to learn more "https://en.wikipedia.org/wiki/List_of_HTTP_status_codes"
Most used HTTP status codes that we support:
Successful response:
200 - OK
Unsuccessful response:
400 - Bad Request
401 – Unauthorized
402 - Payment Required
403 - Forbidden
405 - Method Not Allowed
408 - Request Timeout
500 – Internal Server Error
501 - Not Implemented
2.5 HTTP API Codes
0 - OK
101 - Internal application error
104 - Sending from client's IP address not allowed
111 - Unknown query type (typeparameter)
113 - No credit on account balance
140 - No information about MSISDN (Format of MSISDN number is correct)
142 - Destination is not allowed for this account
161 - MSISDN is missed
162 - MSISDN is incomplete
163 - MSISDN is not exist
170 - Wrong API Key
HTTP Code error | HTTP API Code error |
---|---|
Successful response | |
200 - OK | 0 |
Unsuccessful response | |
404 - Not Found | 140 |
400 - Bad Request | 161, 162, 163 |
401 - Unauthorized | 170 |
402 - Payment Required | 113 |
403 - Forbidden | 104 |
405 - Method Not Allowed | 111 |
500 - Internal Server Error | 101 |