MNP Customer ENUM API

1. Introduction

The HORISEN Customer ENUM API provides an efficient way to retrieve MCC/MNC information of recipient mobile subscriber by sending queries to our MNP Server.

• HORISEN - MNP Server
• Customer - MNP Client

2. Authentication

All ENUM queries require authentication. This is essential for the ENUM to identify which user is making the call so that appropriate results will be returned, as well as for security. For this, the ENUM API uses client IP address and port for authentication.

Please provide your ENUM client IP and port to our support team or your project manager before you start using this interfaces for testing or commercial purpose.

3. MNP request over the ENUM API interface

This method allows you to retrieve information on specific phone numbers.

ENUM resolution operates similarly to reverse DNS lookup queries. To perform the lookup, the E.164 number needs to be transformed in accordance with the following rules:

• Remove non-numeric characters such as spaces, '+', dashes, etc. (e.g. number «+41-787078880» needs to be transformed into «41787078880»);
• Reverse the digits and insert a dot between every digit (e.g.41787078880 becomes 0.8.8.8.7.0.7.8.7.1.4);
• Add suffix domain (e.g. the number now becomes 0.8.8.8.7.0.7.8.7.1.4.DOMAIN).

4. Example of ENUM query over HORISEN MNP Server

dig @194.0.137.85 -p 16090 -t naptr 0.8.8.8.7.0.7.8.7.1.4.enum.horisen.com

5. Example of ENUM response from HORISEN MNP Server

; <<>> DiG 9.10.6 <<>> @194.0.137.85 -p 16090 -t naptr 0.8.8.8.7.0.7.8.7.1.4.enum.horisen.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 50398
;; flags: qr aa; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;0.8.8.8.7.0.7.8.7.1.4.enum.horisen.com.    IN NAPTR

;; ANSWER SECTION:
0.8.8.8.7.0.7.8.7.1.4.enum.horisen.com.    60 IN NAPTR 100 100 "u" "E2U+PSTN:TEL" "!^.*$!TEL:+41787078880;spid=2095;mcc=228;mnc=02;npdi>!" .

;; Query time: 39 msec
;; SERVER: 194.0.137.85#16088(194.0.137.85)
;; WHEN: Thu Mar 07 09:20:14 CET 2019
;; MSG SIZE  rcvd: 176

6. ENUM Rcode and Status codes

Successful response: you will always get back MCC/MNC information:

0.8.8.8.7.0.7.8.7.1.4.enum.horisen.com. 60 IN NAPTR 100 100 "u"  "E2U+PSTN:TEL" "!^.*$!<TEL:+41787078880;spid=2095;mcc=228;mnc=02;npdi>!" .

Unsuccessful responses:

; <<>> DiG 9.10.6 <<>> @194.0.137.85 -p 16090 -t naptr  5.3.7.2.6.2.3.1.enum.horisen.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 17422
;; flags: qr aa; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;5.3.7.2.6.2.3.1.enum.horisen.com. IN   NAPTR

;; ANSWER SECTION:
5.3.7.2.6.2.3.1.enum.horisen.com. 60 IN NAPTR   100 100 "u" "E2U+PSTN:TEL" "!^.*$!TEL;statuscode=140;message=No MSISDN Information;!" .

;; Query time: 38 msec
;; SERVER: 127.0.0.1#16088(127.0.0.1)
;; WHEN: Mon Aug 02 12:02:36 EEST 2021
;; MSG SIZE  rcvd: 171


; <<>> DiG 9.10.6 <<>> @194.0.137.85 -p 16090 -t naptr a.enum.horisen.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: FORMERR, id: 19144
;; flags: qr aa; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; WARNING: EDNS query returned status FORMERR - retry with '+noedns'

;; QUESTION SECTION:
;a.enum.horisen.com.            IN      NAPTR

;; ANSWER SECTION:
a.enum.horisen.com.     60      IN      NAPTR   100 100 "u" "E2U+PSTN:TEL"  "!^.*$!TEL;statuscode=112;message=Cannot parse query: a.enum.horisen.com. expected digit on position 0 but found a;!" .

;; Query time: 0 msec
;; SERVER: 127.0.0.1#16088(127.0.0.1)
;; WHEN: Mon Aug 02 12:04:00 EEST 2021
;; MSG SIZE  rcvd: 202

The response code of a response indicates what happened on the server when trying to answer the query. The code is a 4 bit value and part of the header of a DNS message. For details see Rcode page.

Name	Value	Description
NOERROR	RCODE:0	DNS Query completed successfully.
FORMERR	RCODE:1	DNS Query Format Error.
SERVFAIL	RCODE:2	Server failed to complete the DNS request.
NXDOMAIN	RCODE:3	Domain name does not exist.

HORISEN Customer ENUM API mostly uses the first three Rcodes (0, 1, and 2) when sending ENUM response.

In addition to Rcodes, HORISEN Customer ENUM API uses “statuscode” with “message” to provide more detailed error descriptions.

Status Code	Description
101	Internal application error.
103	No account with given username and password.
104	Sending from client's IP address not allowed.
110	MSISDN is missing.
112	MSISDN Format is wrong.
140	No information about MSISDN.
142	Destination is not allowed for this account.
302	ENUM query is not NAPTR query.