Thank you for filling out the form. One of our mobile experts will be in touch shortly to discuss your inquiry.
If you have any other questions please feel free to email us directly at info@mitto.ch
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 via ENUM API interface.
ENUM API Interface
The ENUM API is accessed through a Uniform Resource Identifier (URI)
consisting of the following elements:
- Base Zone
- Phone Number
The ENUM API is reachable using the following interfaces:
Primary Interface IP 185.124.68.84 Port 6363
Secondary Interface IP 185.124.68.85 Port 6363
The API uses IP whitelists to authenticate the users, and it is therefore required to register the IP address of the client to access the ENUM lookup API. Your account manager or the support desk can help you with the whitelisting procedure.
ENUM API URI
The ENUM API can be accessed through the following base zone:
e164.arpa
Complete URI – lookup a number
The complete lookup ENUM URI is built as follows:
[Reverse MSISDN number separated by dots].e164.arpa
e.g. to lookup the number +491XXXXXXXXX using the ENUM API the following URI is required:
4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa
Using the DIG command, it is very easy to access MITTO’s ENUM Lookup API:
dig @185.124.68.84 –p 6363 IN NAPTR 4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa
The answer to the lookup request will have the following format (relevant extract):
;; ANSWER SECTION:
4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa. 3600 IN NAPTR 0 0 "u" "E2U+SIP" "!^.*$!sip:+491XXXXXXXXXims.mnc02.mcc262.3gppnetwork.org;cost=0.000600000000;
ported=0!" .
The main parameters returned by the lookup request are the Mobile Country Code (MCC), the Mobile Network Code (MNC) and the cost associated to the service:
Number = +491XXXXXXXXX
MCC = 262 (Germany)
MNC = 02 (Vodafone)
cost = 0.000600000000
ported = NOT PORTED
Complete URI – lookup multiple numbers
The Number Lookup service can be retrieved for multiple MSISDN by using the
same DIG request with multiple contents:
dig @185.124.68.84 –p 6363 IN NAPTR 4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa 5.5.6.0.0.0.0.1.1.5.1.9.4.e164.arpa
In this case the answer to the lookup request will have the following format (relevant extract):
;; ANSWER SECTION:
4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa. 3600 IN NAPTR 0 0 "u" "E2U+SIP" "!^.*$!sip:+491XXXXXXXXX@ims.mnc02.mcc262.3gppnetwork.org;cost=0.000600000000;
ported=0!" .
;; ANSWER SECTION:
5.5.6.0.0.0.0.1.1.5.1.9.4.e164.arpa. 3600 IN NAPTR 0 0 “u” “E2U+SIP” “!^.*$!sip:+491XXXXXXXXX@ims.mnc07.mcc262.3gppnetwork.org;cost=0.000600000000;
omnc=01;ported=1!” .
The main information returned by the request is similar to the previous example:
Number = +491XXXXXXXXX
MCC = 262
MNC = 02
cost = 0.000600000000
ported = NOT PORTED
Number = +491XXXXXXXXX
MCC = 262
MNC = 07 (O2)
cost = 0.000600000000
ported = PORTED OMNC = 01 (the number was ported from T-Mobile to O2)
ENUM API Responses
Beside the basic information about the subscription network of a given MSISDN, the API can provide upon request additional information regarding the status of the subscriber number.
The following table indicates additional information that can be retrieved using the ENUM API:
| Parameter | Type | Description |
| sip | 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 (‘0’ not ported, ‘1’ ported) |
| omnc | String | In case of ported number, it provides in form of MNC the network code the MSISDN originally belonged to |
| roaming | Boolean | Provides information on the roaming status of the MSISDN (‘0’ in the home network, ‘1’ in roaming) |
| rmcc | String | In the case the MSISDN is roaming, it provides as MCC the country code where the line is at the moment of the request |
| 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 (‘0’ subscriber available, ‘1’ subscriber absent) |
| gsmcode | Number | Returns the GSM error code giving detailed information. Below the description of the GSM error codes |
| err | String | Provides the specific error to a request fault |
The ENUM API provides together with the lookup answer a series of error codes: GSM error codes, API specific error codes, and status error codes. These can be used to interpret the reason of a call failure.
The following table provides the description of the possible status code values:
| ENUM code | Description | Reason |
| NOERROR | ok | |
| REFUSED | Unauthorized | – IP not registered – ENUM not activated |
| SERVFAIL | Wrong formatted request | Missing parameter(s) |
The following table provides an overview about the API error codes and their meaning:
| Error Code | Description | Reason |
| 0 | Success | The lookup was successfully executed |
| 1 | Unknown Error | A generic error occurred |
| 2 | Unauthorized | Missing or invalid credentials |
| 3 | Insufficient funds | Refused due to insufficient funds |
| 4 | Not allowed | Lookup type not allowed |
| 5 | Invalid MSISDN | Not properly formatted MSISDN |
| 6 | MSISDN not mobile | The number doesn’t belong to a mobile carrier |
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 |
Examples
This section provides further example on the usage of the Number
Lookup ENUM API, applied to different numbering scenarios.
Lookup a number
dig @185.124.68.84 -p 6363 IN NAPTR 4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa
The Number Lookup reply to the command will be (full response):
; <<>> DiG 9.14.2 <<>> @185.124.68.84 -p 6363 IN NAPTR 4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 15783
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; QUESTION SECTION:
;4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa. IN NAPTR
;; ANSWER SECTION:
4.3.2.1.5.5.5.2.7.1.9.4.e164.arpa. 3600 IN NAPTR 0 0 "u" "E2U+SIP" "!^.*$!sip:+491XXXXXXXXX@ims.mnc02.mcc262.3gppnetwork.org;cost=0.000600000000;
ported=0!" .
;; ADDITIONAL SECTION:
RequestId. 6000 IN TXT "1d2ae619-a739-4b5a-ac50-15a23e6c89c7"
;; Query time: 46 msec
;; SERVER: 185.124.68.84#6363(185.124.68.84)
;; WHEN: Fri Oct 08 13:17:28 Central Europe Daylight Time 2021
Number lookup information provided:
Number = +491XXXXXXXXX
MCC = 262 (Germany)
MNC = 02 (Vodafone)
cost = 0.000600000000
ported = NOT PORTED
Lookup a ported number
dig @185.124.68.84 -p 6363 IN NAPTR 1.3.5.0.0.0.0.1.1.5.1.9.4.e164.arpa
The Number Lookup reply to the command will be:
; <<>> DiG 9.14.2 <<>> @185.124.68.84 -p 6363 IN NAPTR 1.3.5.0.0.0.0.1.1.5.1.9.4.e164.arpa ; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 16373
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; QUESTION SECTION:
;1.3.5.0.0.0.0.1.1.5.1.9.4.e164.arpa. IN NAPTR
;; ANSWER SECTION:
1.3.5.0.0.0.0.1.1.5.1.9.4.e164.arpa. 3600 IN NAPTR 0 0 "u" "E2U+SIP" "!^.*$!sip:+491XXXXXXXXX@ims.mnc07.mcc262.3gppnetwork.org;cost=0.000600000000;
omnc=01;ported=1!" .
;; ADDITIONAL SECTION:
RequestId. 6000 IN TXT "535a41ba-097a-41a7-857d-38077c0a3cf0"
;; Query time: 68 msec
;; SERVER: 185.124.68.84#6363(185.124.68.84)
;; WHEN: Fri Oct 08 13:26:02 Central Europe Daylight Time 2021
Number lookup information provided:
Number = +491XXXXXXXXX MCC = 262 (Germany) MNC = 07 (O2)
cost = 0. 000600000000 ported = PORTED
OMNC = 01 (the number was ported from T-Mobile to O2)
Lookup a number while roaming
dig @185.124.68.84 -p 6363 IN NAPTR 1.1.1.8.1.5.1.4.6.7.1.9.4.e164.arpa
; <<>> DiG 9.14.2 <<>> @185.124.68.84 -p 6363 IN NAPTR 1.1.1.8.1.5.1.4.6.7.1.9.4.e164.arpa ; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 44012
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; QUESTION SECTION:
;1.1.1.8.1.5.1.4.6.7.1.9.4.e164.arpa. IN NAPTR
;; ANSWER SECTION:
1.1.1.8.1.5.1.4.6.7.1.9.4.e164.arpa. 3600 IN NAPTR 0 0 "u" "E2U+SIP" "!^.*$!sip:+491XXXXXXXXX@ims.mnc03.mcc262.3gppnetwork.org;absent=0;cost=0.00120 0000000;gsmCode=0;imsi=26203XXXXXXXXXXX;omnc=07;ported=1;roaming=1!" .
;; ADDITIONAL SECTION:
RequestId. 6000 IN TXT "8f88b5c1-c343-4821-a751-d32f0a252a28"
;; Query time: 860 msec
;; SERVER: 185.124.68.84#6363(185.124.68.84)
;; WHEN: Fri Oct 08 13:35:41 Central Europe Daylight Time 2021
;; MSG SIZE rcvd: 285
Based on the information provided in the Answer section above, the Number Lookup request provided the following details:
Number = +491XXXXXXXXX MCC = 262 (Germany) MNC = 03 (O2)
cost = 0.001200000000 ported = PORTED
OMNC = 07 (the number was ported from O2 to O2)
roaming = NUMBER IN ROAMING
rmcc =
imsi = 26203XXXXXXXXXXX (International Mobile Subscriber Identity)
absent = 0, the number is NOT ABSENT at the moment of the request