MNP Supplier HTTP API v1.1

1. Introduction

HORISEN MNP Supplier HTTP API provides an efficient way to retrieve MCC and MNC information of recipient mobile subscriber by sending querying to MNP HTTP Service developed by MNP Supplier (MNP Source further).

The subject domain of an endpoint URL is:

https://{your mnp api server domain name}/horisen-mnp/v1

This document describes necessary parameters and samples to demonstrate users how to use the HORISEN MNP Supplier HTTP API for new MNP Source development.

1.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, MNP Supplier can use VPN access to their MNP HTTP Service or should use Basic authorization.

Authentication data are sent via HTTP header "Authorization".
Steps to construct authorization header:

  1. Base64 encode the API Key.
  2. 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.

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

Where {your mnp api server domain name} can be your public domain name or public/private IP:port if you will use VPN access.
And /horisen-mnp is base path for HORISEN MNP Supplier HTTP API.

Please keep in mind that currently only v1 is supported.

2. Method Overview

Endpoint for retrieving MCC and MNC information for specific phone number.

GET/number-lookup?msisdn={msisdn}
Returns MCC and MNC information for specific phone number.Read More

3. Method Details

Endpoint for retrieving MCC and MNC information for specific phone number.

GET/number-lookup?msisdn={msisdn}
Returns MCC and MNC information for specific phone number.Up
Method Overview

By using MNP Number Lookup method, you can retrieve MCC and MNC information for specific phone number.

URL Parameters
Name Type Description
msisdn (required) string MSISDN number in international format E.164.

Example:

https://mnp.example.com/horisen-mnp/v1/number-lookup?msisdn=525614157575
Responses
Code Description Links
200 Phone number data. No links.
default Unexpected Error. No links.
Success Response 200: Phone number data
{
    "number": "525614157575",
    "ported": true,
    "mcc": "334",
    "mnc": "20",
    "country": "Mexico",
    "operator": "TELCEL",
    "numbertype": "mobile"
}
Name Type Description
number (required) string Number.
ported (required) boolean "True" means ported at least once, "false" means no porting record and queried number still belongs to original operator.
mcc (required) string Mobile country code.
mnc (required) string Mobile network code.
country string Country.
operator string Operator.
numbertype string Possible values: mobile, fix, wireless, voip, m2m, satellite.
Error Response Unexpected Error: Default
{
  "errorcode":  {your error code},
  "errordesc": {your error description}
}
Name Type Description
errorcode (required) integer Error code.
errordesc (required) string Error description.

Unsuccessful Response should be sent only for the response with HTTP Status Code 500 "Internal Server Error" (see point 4. HTTP Status Codes).

4. HTTP Status Codes

Every HTTP response has a status code sent back by the MNP HTTP Service to define how the HORISEN MNP Server 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 en.wikipedia.org/wiki/List_of_HTTP_status_codes.

Most used HTTP Status Codes that we support:

Successful response

Status code Status Description
200 OK Successful response.

Unsuccessful responses

Status code Status Description
400 Bad Request MSISDN parameter is missing or it is incomplete.
404 Not Found No information about MSISDN (MSISDN parameter is correct and complete).
401 Unauthorized Wrong API Key if you will use API Key Authentication.
402 Payment Required No credit on account balance.
403 Forbidden IP address is not whitelisted or has not the necessary permissions.
405 Method Not Allowed The method is not supported in case if request URL was not correct (/horisen-mnp/v1/number-lookup).
408 Request Timeout You can use this HTTP Status Code when your MNP HTTP service is timed out or we can use default Timeout value (in seconds) on the MNP Server side.
500 Internal Server Error A generic error message, you can send also Unsuccessful Response with errorcode and errordesc. We will use this Response to send you notifications and you can check your MNP HTTP service logs to fix the errors.

If you want to support other HTTP Status Codes, please write to us and we will handle them correctly.