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:

Parameter Type Description
msisdn String Provides the Number Lookup destination address. The number must be given in MSISDN format:
no leading zeros nor plus sign ‘+’. A valid MSISDN contains the international country prefix and
the number without the leading zeros, e.g. 49123456789
key String Access key of your account – necessary to use the API

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:

Parameter Type Description
msisdn String The MSISDN added with a ‘+’ sign as preamble
mnc String Mobile Network Code. Length of the MNC can be two or three digits
mcc String Mobile Country Code. Length of the MNC can be three digits only
cost Decimal The cost of the lookup request
ported Boolean Provides information on the mobile number portability status of the MSISDN (‘false’ not ported, ‘true’ ported)
portedNetwork Network object Information about the ported network where the number was ported to. Find below the description of the Network Object type.
roaming Boolean Provides information on the roaming status of the MSISDN (‘false’ in the home network, ‘true’ in roaming)
originalMnc String Information about the original network the number was ported from given as MNC
originalNetwork Network object If ported is false the original network contains the information of the current network.
If ported is true the original network contains the information of the network the number was ported from.
Find below the description of the Network Object type
roamingMcc String Information about the roaming country. Given as MCC
roamingMnc String Information about the roaming network. Given as MNC
roamingNetwork Network object Information about the network the number is roaming. Find below the description of the Network Object type
msc String Provides the Global Title of the Mobile Switching Centre (the serving network node)
imsi String Provides the International Mobile Subscriber Identity, this field identifies uniquely the user of a mobile network
absent Boolean Informs about the status of the user at the time of the lookup request (‘false’ subscriber available, ‘true’ subscriber absent)
gsmcode Number Returns the GSM error code giving detailed information. Below the description of the GSM error codes
date String UTC date and time in when the result has been created. Date is given as ISO 8601. Example: “2015-02-14T13:17:53Z”
response Number The response code gives further information about the state of the lookup request

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

Parameter Type Description
networkName String The name of the network, e.g., ‘T-Mobile’
countryName String The name of the country, e.g., ‘Germany’
countryPrefix String The international prefix of the country, e.g., ‘49’ for Germany

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

GSM error code Description
0 No error
1 Unknown subscriber
2 Unknown subscriber – NR changed
5 Unidentified subscriber
6 Absent subscriber for SM
7 Unknown equipment
8 Roaming not allowed
9 Illegal subscriber
10 Bearer service not provisioned Teleservice not provisioned
12 Illegal equipment
13 Call barred
21 Facility not supported
27 Absent subscriber
28 Incompatible MS terminal error
31 Subscriber busy for SMS MT
32 Equipment failure
33 MS memory capacity exceeded
34 GSM system failure
35 GSM Data Error – data missing
36 GSM Data Error
45 Subscriber busy
100/101 Internal equipment error
103/104/105 Unspecified GSM error
150/151 Request timeout

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

Response code HTTP status code Description Reason
0 200 Success The lookup was successfully executed
1 500 Unknown Error An undocumented error occurred
2 401 Unauthorized Missing or invalid credentials
3 200 Insufficient funds Refused due to insufficient funds
4 412 Not allowed Lookup type not allowed
5 200 Invalid or no MSISDN Not properly formatted number (not MSISDN), or no input number provided
6 200 Not a mobile MSISDN