Mitto Number Lookup HTTP

Introduction

Mitto’s Number Lookup service provides a simple way to retrieve mobile subscription information given one or more mobile subscriber number (MSISDN). The service is available both via ENUM interface or REST API. This document describes the necessary parameters and how to use the Number Lookup service thanks to HTTP GET/POST API commands.

HTTP(s) URL

The Number Lookup service is accessible through an HTTP connection (and its secure version) using the following base URLs for both GET and POST requests:

PRIMARY SITE
http://nis1.mitto.ch/lookup
https://nis1.mitto.ch/lookup

SECONDARY SITE
http://nis2.mitto.ch/lookup
https://nis2.mitto.ch/lookup

The API supports JSON formats. It is possible to specify which format shall be adopted by using following URL layout:

https://nis1.mitto.ch/lookup.json

HTTP(s) Authentication

Mitto’s Number Lookup HTTP API requires the users to be authenticated any time they submit the URL call. This is done by using a user’s unique API key. The authentication is performed by providing such API key in two possible ways:

In the URL call
https://api.mitto.ch/lookup?key=YourAPIKey

In Mitto’s custom header
X-Mitto-API-Key: YourApiKey

Aiming to make the service secure, an additional level of authentication is required. Each client calling the lookup API must have a whitelisted IP address. Prior to access the service our support team will contact you to add your IP addresses to our whitelist.

HTTP(s) GET

This section describes how to use Mitto number lookup API through HTTP
GET requests and provides some call examples.

The generic URL has the following format:

https://nis1.mitto.ch/lookup.json?[PARAMETER]

where possible values for the PARAMETER are:

HTTP(s) GET – Lookup a number

The following HTTP GET request can be used to lookup a certain number
(+491XXXXXXXXX) using the JSON format:

https://nis1.mitto.ch/lookup.json?key=YourApiKey;amp;msisdn=491725551234

The response to the HTTP call will be the following:

[
{
"cost": 0.001700000000,
"date": "2021-08-02T10:18:18.729Z", "mcc": "262",
"mnc": "02",
"msisdn": "+491XXXXXXXXX", "originalMnc": "02", "originalNetwork": {
"countryName": "Germany", "countryPrefix": "49", "networkName": "Vodafone"
},
"ported": false, "response": 0
}
]

where the main information returned by the request are:

Number = +491XXXXXXXXX
MCC (Mobile Country Code): 262, which is Germany
MNC (Mobile Network Code): 02, which is Vodafone
PORTED: not ported

originalNetwork (this section provides additional information about the MSISDN Mobile Carrier)
networkName (Name of the network): Vodafone
countryName (Name of the country): Germany
countryPrefix (International prefix of the country): 49
COST: 0.0017
DATE: Date and time of the request given as UTC
RESPONSE: 0 meaning everything was successful

4.2 HTTP(s) GET – Lookup multiple numbers

The API call can be used to request the lookup of multiple numbers. The following HTTP GET request can be used to lookup two different numbers (+491XXXXXXXX4 and +491XXXXXXXX0):

https://nis1.mitto.ch/lookup.json?key=YourApiKey;amp;msisdn=491XXXXXXXX4,491XXXXXXXX0

[
{
}, {
"cost": 0.000600000000,
"date": "2021-08-02T10:23:45.525Z", "mcc": "262",
"mnc": "02",
"msisdn": "491XXXXXXXX4", "originalMnc": "02", "originalNetwork": {
"countryName": "Germany", "countryPrefix": "49", "networkName": "Vodafone"
},
"ported": false, "response": 0
"cost": 0.000600000000,
"date": "2021-08-02T10:23:45.538Z", "mcc": "262",
"mnc": "02",
"msisdn": "4915906216790", "originalMnc": "07", "originalNetwork": {
"countryName": "Germany", "countryPrefix": "49", "networkName": "O2"
},
"ported": true, "portedNetwork": {
"countryName": "Germany", "countryPrefix": "49", "networkName": "Vodafone"
},
"response": 0 }
]

The response above contains the following information:

First number

Number = +491XXXXXXXXX
MCC (Mobile Country Code): 262, which is Germany
MNC (Mobile Network Code): 02, which is Vodafone
PORTED: not ported

originalNetwork (this section provides additional information about the MSISDN Mobile Carrier)

networkName (Name of the network): Vodafone
countryName (Name of the country): Germany
countryPrefix (International prefix of the country): 49

COST: 0.0017
DATE: Date and time of the request given as UTC
RESPONSE: 0 meaning everything was successful

Second number

Number = +491XXXXXXXXX
MCC (Mobile Country Code): 262, which is Germany
MNC (Mobile Network Code): 07, which is O2
PORTED: ported

portedNetwork (this section provides additional information about the MSISDN Mobile Carrier)

networkName (Name of the network): Vodafone
countryName (Name of the country): Germany
countryPrefix (International prefix of the country): 49

originalMNC: Mobile Network Code of the mobile carrier the number belonged to originally

originalNetwork (it contains more information about the original mobile carrier – first activation)

networkName (Name of the network): Vodafone countryName (Name of the country): Germany countryPrefix (International prefix of the country): 49

COST: 0.0017
DATE: Date and time of the request given as UTC
RESPONSE: 0 (the request was successful)

5 HTTP(s) POST

This section describes how to use Mitto number lookup API through HTTP
POST requests.

A POST call requires to provide the URL, the API Key and the content format in the Header, while the phone number(s) subject of the request in the Body part: POST URL:

https://nis1.mitto.ch/lookup.json

POST Header:

X-Mitto-API-Key: YourApiKey
Content-Type: application/json

POST Body:

{
“msisdn”: “491XXXXXXXXX”
}

The response will be in line with the answer provided in the previous section related to the HTTP GET requests.

In case multiple numbers have to be requested, they shall be provided in the body in form of a list: POST Body:

{
“msidn”: [ “49172555”, “49172556” ]
}

Please refer to the Examples section to see more examples of HTTP POST API requests.

6 HTTP(s) GET/POST Responses

This section describes the parameters returned by the Number Lookup API
response in case the HTTP status code is 200.

The following table indicates additional information that can be retrieved using the Lookup API:

The Network Object field contains more detailed information about the mobile carrier. The following table explains the content of the Network Object type:

The following table provides an overview about the GSM error codes:

In case the HTTP request cannot retrieve a successful response, the following status codes are provided: