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

Subject Domain in the 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.

3. Method Details

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

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.