HTTP interface

HTTP Interface for the Sinch Number Lookup service.

The first instance of each term is linked to the definition on our Sinch Support Community.

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 are available in the CAD (Client Account Details) document provided to you by your account manager.

For servers in Europe

Number Lookup HTTP Server Host:Port
Primary eu3.httplookup.api.sinch.com:3700
Backup eu1.httplookup.api.sinch.com:3700
Primary eu3.httplookup.api.sinch.com:3701
Backup eu1.httplookup.api.sinch.com:3701

For servers in the US

Number Lookup HTTP Server Host:Port
Primary us3.httplookup.api.sinch.com:3700
Backup us2.httplookup.api.sinch.com:3700
Primary us3.httplookup.api.sinch.com:3701
Backup s2.httplookup.api.sinch.com:3701

Query specification

Request

You can format the request like this:

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

Response

The response will vary depending on the service you're using.

Number Portability Lookup service response examples:

Example 1Example 2
Copy
Copied
result=<result>;imsi=<imsi></imsi></result>
Copy
Copied
result=
  <result>;
    imsi=<imsi>;
    location=<location></location></imsi>
  </result>

Real-Time Lookup service response example:

Copy
Copied
result=
  <result>;
    imsi=<imsi>;
      location=<location> </location></imsi>
  </result>

| 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 is not allowed on this service
MSISDN is invalid Wrong format of the MSISDN parameter

Examples

HTTP Request

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

HTTP Request with cache function bypass

Successful response, Number Portability Lookup

Copy
Copied
result=OK;imsi=24008

or

result=OK;imsi=24008;location=46

Unsuccessful response

Copy
Copied
result=UNKNOWN_SUBSCRIBER

Request with successful response, using curl

Copy
Copied
$ 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
Was this page helpful?
Still have a question? Ask the community.