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:

  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.

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