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.
|Number Portability Lookup||MCC + MNC||MCC + MNC|
|Real-Time Lookup||MCC + MNC||
MCC + MNCCountry Code
Handset Status Code
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: “184.108.40.206.220.127.116.11.18.104.22.168.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.
|Primary Number Lookup ENUM Server||22.214.171.124:53|
|Backup Number Lookup ENUM Server||126.96.36.199:53|
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:
188.8.131.52 184.108.40.206.220.127.116.11.3.3.1.e164.arpa IN NAPTR
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:
18.104.22.168.22.214.171.124.3.3.1.e164.arpa. 3 IN NAPTR 10 50 “u” “E2U+pstn:tel” “!^(.*)$!tel:\\\\1\\\;mcc=310\\\;mnc=012!”
Below you will find full examples of queries using the “dig” command.
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 @126.96.36.199 188.8.131.52.184.108.40.206.3.3.1.e164.arpa IN NAPTR ; < <>> DiG 9.8.3-P1 < <>> @220.127.116.11 18.104.22.168.22.214.171.124.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: ;126.96.36.199.188.8.131.52.3.3.1.e164.arpa. IN NAPTR ;; ANSWER SECTION: 184.108.40.206.220.127.116.11.3.3.1.e164.arpa. 3 IN NAPTR 10 50 “u” “E2U+pstn:tel” “!^(.*)$!tel:\\\\1\\\;mcc=310\\\;mnc=012!” . ;; Query time: 206 msec
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 @18.104.22.168 22.214.171.124.126.96.36.199.3.3.1.e164.arpa IN NAPTR ; < <>> DiG 9.8.3-P1 < <>> @188.8.131.52 184.108.40.206.220.127.116.11.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: ;18.104.22.168.22.214.171.124.3.3.1.e164.arpa. IN NAPTR ;; Query time: 202 msec
The list below specifies the Response Codes that can be returned.
|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.|
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
|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.
|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|
The request has the format:
|<username>:<password>||Basic authentication parameters|
|<port>||Port number |
|<msisdn>||MSISDN in international format|
|nocache||Bypass cache function (optional)|
Response when using the Number Portability Lookup service:
Response when using the Real-Time Lookup service:
|<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)|
|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|
HTTP Request with cache function bypass
Successful response, Number Portability Lookup¶
Successful response, Real-Time Lookup¶
Request with successful response, using curl¶
$ curl -v -u user:password http://126.96.36.199:3700/lookup?msisdn=46708100200 * About to connect() to 188.8.131.52 port 3700 (#0) * Trying 184.108.40.206… * Connected to 220.127.116.11 (18.104.22.168) 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: 22.214.171.124: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 126.96.36.199 left intact result=OK;imsi=24004
|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|