Making a Carrier Lookup Request Using HTTP

Overview

The MX Telecom Carrier Lookup service allows the carrier of a given mobile number to be determined.

Making a Carrier Lookup request using HTTP
Parameters for requests
Response from the server

Making a Carrier Lookup request using HTTP

The MX Telecom Carrier Lookup Service exposes an HTTP interface allowing applications with internet connectivity to lookup the carrier of a cell number.

A request for a page using the structure shown below is all that is needed for you to lookup the carrier of a mobile number using the MX Telecom Carrier Lookup Service. The endpoints for these HTTP requests are http://lookup.mxtelecom.com/USLookup for HTTP and https://lookup.mxtelecom.com/USLookup for HTTPS (SSL).

Requests should be sent as a HTTP GET or POST using the parameters listed below.

HTTP/1.1 is enabled so, if sending multiple packets, the TCP/IP connection should be kept open between requests.

Parameters for requests

Name	Description
user	Username of the account to use
pass	Password
msisdn	MSISDN of the mobile phone (eg 12125551234). No leading "+" is required
*note	Note that will be stored in the billing record (maximum 160 characters)
*subaccount	Sub account that will be stored in the billing record (maximum 10 characters)
*response	Specifies how the response will be formed, options are 'text' for extended text format or 'xml', the default is 'simple text'

Where * denotes an optional parameter

The following example shows the an HTTP request that is understood by the MX Telecom Carrier Lookup Service:

http://lookup.mxtelecom.com/USLookup?user=myusername&pass=mypassword&msisdn=12125551234

Parsing responses to GET requests

There are three possible response types, 'simple text' - default, 'extended text' and 'xml'.

In each case the responses to GET requests take into account standard internet three digit reply codes: broadly speaking, 20x implies success, 40x implies bad request, and 50x implies server errors.

When a request is successfully received by the MX Telecom Carrier Lookup Service a HTTP success will be returned to the caller (200 code) and the HTTP body will contain the result of the lookup request.

In the case of a bad request - eg parameters missing/invalid the servlet will return a Bad request or forbidden error (code 40x).

If there is a problem with the MX Telecom Carrier Lookup Service then a 500 Internal server error will be returned. The customer should wait a few seconds and reattempt their lookup.

Parsing simple text response (default response)

The meaning of the response received is:

Value	Description
<network>	Carrier that the mobile number belongs to. See Carrier Codes for possible values.
UNKNOWN	Unrecognised carrier. Please contact us to extend coverage.
FAILURE	Lookup Failed

Extended response types

Both 'extended text' and 'xml' response types contain the same information:

On a successful lookup the following parameters will be returned (*'d parameters are returned where appropriate).

Name	Description
msisdn	The MSISDN that the response relates to
network	The carrier of the MSISDN, is the same as the carrier value described in the simple text response
network_code	The OCN code for the carrier
certainty	The type of lookup that was conducted
*mvno	The name of the mobile virtual network associated with the handset. Note that in some cases this information will not always be available (e.g. if the handset has been turned off for a number of days). As such the lack of an mvno parameter does not necessarily indicate that the number is not associated with a mvno.

Where the following table contains explanations of certainty codes

Certainty Value	Description
0	Failure
1	Prefix Lookup
2	Cached Data
3	Recently Cached Data
4	Known Data

If a lookup has failed the following parameters will be returned

Name	Description
msisdn	The MSISDN that the response relates to
error	A description of the error

Examples of 'extended text' response

Success:

msisdn: 15073800239
network: VIRGIN
network_code: 06939
certainty: 4

Failure:

msisdn: 15073800239
error: Authentication Error

Examples of 'xml' response