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	`us1.httplookup.api.sinch.com:3700` and `us7.httplookup.api.sinch.com:3700`
Backup	`us3.httplookup.api.sinch.com:3700`
Primary	`us1.httplookup.api.sinch.com:3701` and `us7.httplookup.api.sinch.com:3701`
Backup	`us3.httplookup.api.sinch.com:3701`

Note:

We strongly recommend that you set up load balancing between us1 and us7 but either server can be used as primary.

For servers in Australia

Number Lookup HTTP Server	Host:Port
Primary	`au1-1.httplookup.api.sinch.com:3700`
Backup	`au1-2.httplookup.api.sinch.com:3700`
Primary	`au1-1.httplookup.api.sinch.com:3701`
Backup	`au1-2.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