Making a Network Lookup request using HTTP
Overview
The MX Telecom Network Lookup service allows the network of a given mobile number to be determined.
Contents
Making a Network Lookup request using HTTP
The MX Telecom Network Lookup Service exposes an HTTP interface allowing applications with internet connectivity to lookup the network of a mobile number.
A request for a page using the structure shown below is all that is needed for you to lookup the network of a mobile number using the MX Telecom Network Lookup Service. The endpoints for these HTTP requests are http://lookup.mxtelecom.com/Lookup for HTTP and https://lookup.mxtelecom.com/Lookup 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 447781484950). 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 Network Lookup Service:
http://lookup.mxtelecom.com/Lookup?user=myusername&pass=mypassword&msisdn=447781484950
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 Network 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 Network 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> | Network that the mobile number belongs to. See Network Codes for possible values. |
| UNKNOWN | Unrecognised network. 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 network of the MSISDN, is the same as the network value described in the simple text response |
| network_code | The MCC/MNC codes for the network |
| 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: 447963901809 network: TMOBILEUK network_code: 23430 certainty: 3 mvno: virgin
Failure:
msisdn: 447812540311 error: Authentication Error
Examples of 'xml' response
Success:
<?xml version="1.0"?> <response> <msisdn>447963901809</msisdn> <network>TMOBILEUK</network> <network_code>23430</network_code> <certainty>3</certainty> <mvno>virgin</mvno> </response>
Failure:
<?xml version="1.0"?> <response> <msisdn>447812540311</msisdn> <error> <message>Authentication Error</message> </error> </response>
 |
About MX TelecomMX Telecom is a leader in wireless technology. MX Telecom offers an easily accessible gateway to data, voice and video messaging services including 2-way and premium SMS, multimedia messaging, interactive voice response, location-based services, video short codes, Internet and TV related solutions. For more information, MX Telecom can be reached on 0845 666 7778, or via email at sales@mxtelecom.com. |
