HORISEN 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 querying 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 will 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 similar with 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 add 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.

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 uses mostly first three Rcode: 0, 1 and 2 when send ENUM response.

In addition to Rcode HORISEN Customer ENUM API uses “statuscode” with “message” to describe errors more detailed.

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