Number Lookup

Overview

Introduction

The core functionality of the Number Lookup Service is to provide information about the MSISDNs queried. MSISDN in - information about the MSISDN out.

In some countries information is accessible via national MNP databases and in some markets the only way to get information about a certain MSISDN is to query the HLR of the network the subscriber is connected to.

To provide data of highest quality we have created a Number Lookup service that combines data sourced directly from local number portability databases with an extensive global HLR coverage powered by our MNO partners. The service is built on a true carrier grade platform developed by our Operator division, ensuring excellent performance in terms of availability, throughput and latency. Just like all Sinch’s services the Number Lookup service is fully redundant. Our Number Lookup service is accessible via two interfaces: ENUM and HTTP/HTTPS.

The use cases for Number Lookup services are many but most common is to use Number Lookup for Call- and SMS routing optimizing, authentication services and number database cleaning. Knowing which network a subscriber is connected to is key to create a high quality messaging service and information about in which country a subscriber is located in, has proven very useful in authentication services.

Number Portability Lookup and Real-Time Lookup

Depending on the use case different data about the MSISDN is needed - that’s why we have packaged our Number Lookup services in to two different products: Number Portability Lookup and Real-Time Lookup. The Number Portability Lookup service is optimized for Call and SMS routing and provides you with MCC+MNC of the operator the subscriber belongs to. Data sources used for the service are national MNP databases and HLR queries. The Real-Time Lookup service is based on real-time HLR queries only, and is commonly used for authentication services where additional information in addition to MCC+MNC is needed.

Input for a Number Lookup query is always an MSISDN - the table below illustrates which data is returned when using our Number Lookup services via the two interfaces.

  ENUM HTTP/HTTPS
Number Portability Lookup MCC + MNC MCC + MNC
Real-Time Lookup MCC + MNC
MCC + MNCCountry Code
Handset Status Code

ENUM Interface

ENUM Protocol

ENUM is an abbreviation for Electronic Numbering Mapping and is a protocol used to translate E.164 telephone numbers (i.e. standard telephone numbers like +447786852522) into a format that can be used in Internet communications. The parameters used in addition to IP address and port number is NAPTR, which is the record type used and e164.arpa which is the domain.

To translate an MSISDN into ENUM format you remove all non-digit characters, add dots between each digit and then reverse the order of the digits. Finally you add the domain “e164.arpa” to the end. As an example an MSISDN in E.164 format, +447786852522, would using ENUM translate to: “2.2.5.2.5.8.6.8.7.7.4.4.e164.arpa”.

How To Connect

Please find the IP address and port number for our ENUM Lookup Server in the table below. The only identifier needed to connect is the IP address you connect from.

Server Host:Port
Primary Number Lookup ENUM Server 93.158.78.4:53
Backup Number Lookup ENUM Server 195.84.167.34:53

Query Specification

Question

The question has the format <IP-address> <MSISDN-in-ENUM-Format> e164.arpa IN NAPTR

As an example the request for MSISDN +13392986156 would look like this:

93.158.78.4 6.5.1.6.8.9.2.9.3.3.1.e164.arpa IN NAPTR

Answer

The answer section will contain a NAPTR record with the MSISDN queried in ENUM format together with the MCC and MNC for the MSISDN queried.

As an example the answer section to the question above looks like this:

6.5.1.6.8.9.2.9.3.3.1.e164.arpa. 3 IN NAPTR 10 50 “u” “E2U+pstn:tel” “!^(.*)$!tel:\\\\1\\\;mcc=310\\\;mnc=012!”

Examples

Below you will find full examples of queries using the “dig” command.

Successful Query

A successful query returns a NAPTR record containing the queried MSISDN in ENUM format as well as MCC and MNC for the MSISDN in the answer section.

dig @93.158.78.4 6.5.1.6.8.9.2.9.3.3.1.e164.arpa IN NAPTR

; < <>> DiG 9.8.3-P1 < <>> @93.158.78.4 6.5.1.6.8.9.2.9.3.3.1.e164.arpa IN NAPTR
;; ->>HEADER< <- opcode: QUERY, status: NOERROR, id: 9512
;; flags: qr; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;6.5.1.6.8.9.2.9.3.3.1.e164.arpa. IN NAPTR
;; ANSWER SECTION:
6.5.1.6.8.9.2.9.3.3.1.e164.arpa. 3 IN NAPTR 10 50 “u” “E2U+pstn:tel”
“!^(.*)$!tel:\\\\1\\\;mcc=310\\\;mnc=012!” .
;; Query time: 206 msec

Unsuccessful Query

The answer to an unsuccessful query will not contain any answer section. No NAPTR record is return and the response code will be received in the status field.

dig @93.158.78.4 6.5.1.6.8.9.2.9.3.3.1.e164.arpa IN NAPTR

; < <>> DiG 9.8.3-P1 < <>> @93.158.78.4 6.5.1.6.8.9.2.9.3.3.1.e164.arpa IN NAPTR
;; ->>HEADER< <- opcode: QUERY, status: SERVFAIL, id: 9512 ;; flags: qr; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 0 ;; QUESTION SECTION: ;6.5.1.6.8.9.2.9.3.3.1.e164.arpa. IN NAPTR ;; Query time: 202 msec

Response Codes

The list below specifies the Response Codes that can be returned.

Response Code Description
0 (NO ERROR) Successful query - answer section is returned.
2 (SERVFAIL) Improperly formatted query - no answer section is returned.
3 (NXDOMAIN) MSISDN not valid - no answer section is returned.
5 (REFUSED) Source IP is unauthorized - no answer section is returned.

HTTP Interface

How To Connect

Please find the hosts and port numbers for our Number Lookup HTTP/HTTPS server in the table below. Your username and password is available in the CAD (Client Account Details) document provided to you by your account manager.

For servers in Europe

Server Host:Port
Primary Number Lookup HTTP Server http-eu3.clxcommunications.com:3700
Backup Number Lookup HTTP Server http-eu1.clxcommunications.com:3700
Primary Number Lookup HTTPS Server http-eu3.clxcommunications.com:3701
Backup Number Lookup HTTPS Server http-eu1.clxcommunications.com:3701

For servers in the U.S.

Server Host:Port
Primary Number Lookup HTTP Server http-us3.clxcommunications.com:3700
Backup Number Lookup HTTP Server http-us2.clxcommunications.com:3700
Primary Number Lookup HTTPS Server http-us3.clxcommunications.com:3701
Backup Number Lookup HTTPS Server http-us2.clxcommunications.com:3701

Query Specification

Request

The request has the format:

http://<username>:<password>@<server>:<port>/lookup?msisdn=[&nocache]
Parameter Description
<username>:<password> Basic authentication parameters
<server> Authority [93.158.78.4]
<port> Port number [3700]
<msisdn> MSISDN in international format
nocache Bypass cache function (optional)

Response

Response when using the Number Portability Lookup service:

result=<result>;imsi=<imsi>

or

result=<result>;imsi=<imsi>;location=<location>

Response when using the Real-Time Lookup service:

result=<result>;imsi=<imsi>;location=<location>
Parameter Description
<result> Lookup result (Response Code)
<imsi> MCC+MNC corresponding to the MSISDN (only included when result is OK)
<location> Country Code of current handset location (only included when result is OK)

Response Codes

Result Description
OK The request was successful
DATA_MISSING The data was missing
UNKNOWN_SUBSCRIBER The subscriber is unknown
CALL_BARRED The service is restricted by the destination network
ABSENT_SUBSCRIBER_SM The subscriber is absent
UNEXPECTED_DATA_VALUE An unexpected data value in the request
SYSTEM_FAILURE A system failure occurred in the HLR
FACILITY_NOT_SUPPORTED Short message facility is not supported
TELE_SERVICE_NOT_PROVISIONED SMS teleservice is not provisioned
HLR_REJECT The HLR request was rejected
HLR_ABORT The HLR (or some other entity) aborted the request. No response to the request was received
HLR_LOCAL_CANCEL No response for the HLR request was received
TIMEOUT No response to the request was received
REQUEST_THROTTLED Maximum ongoing requests exceeded
IMSI_LOOKUP_BLOCKED Request is blocked
Mandatory parameter msisdn not found Some mandatory parameter are missing in the request
MSISDN range is not accepted The number are not allowed on this service
msisdn is invalid Wrong format of the MSISDN parameter

Examples

HTTP Request

http://username:password@93.158.78.4:3700/lookup?msisdn=46708100100

HTTP Request with cache function bypass

Successful response, Number Portability Lookup

result=OK;imsi=24008

or

result=OK;imsi=24008;location=46

Successful response, Real-Time Lookup

result=OK;imsi=24008;location=46

Unsuccessful response

result=UNKNOWN_SUBSCRIBER

Request with successful response, using curl

$ curl -v -u user:password http://93.158.78.4:3700/lookup?msisdn=46708100200
* About to connect() to 93.158.78.4 port 3700 (#0)
* Trying 93.158.78.4…
* Connected to 93.158.78.4 (93.158.78.4) port 3700 (#0)
* Server auth using Basic with user ‘user’
> GET /lookup?msisdn=46708100200 HTTP/1.1
> Authorization: Basic dXNlcjpwYXNzd29yZA==
> User-Agent: curl/7.30.0
> Host: 93.158.78.4:3700
> Accept: */*
>
< HTTP/1.1 200 OK, Success
< Date: Mon, 12 Feb 2014 11:00:41 +0100
< Content-Length: 20
< Content-Type: text/plain; charset=ISO-8859-1
<
* Connection #0 to host 93.158.78.4 left intact

result=OK;imsi=24004

Glossary

CC Country Code
dig Domain Information Groper, command-line tool for querying DNS
DNS Domain Name System
ENUM Electronic Numbering Mapping
E.164 Format for international telephone numbers (i.e .+467012345)
HLR Home Location Register
MCC Mobile Country Code
MNC Mobile Network Code
MNP Mobile Number Portability
NAPTR Name Authority Pointer - resource record type in the DNS of the internet
MSISDN Telephone number to the SIM card in a mobile phone (i.e. 467012345)
e164.arpa The domain used for DNS mapping