UK SMS HTTP
Response parameters and formats
All requests are acknowledged with an HTTP response. The HTTP status code will indicate whether or not the operator lookup request was accepted.
HTTP Response status codes
| HTTP status code |
Description |
|---|---|
|
200 |
The request was accepted. |
|
400-499 |
The request was invalid. You will need to check the request parameters before resending the request. |
|
500-599 |
There was a problem receiving your request. |
You can choose the level of detail returned and the format of the response body you receive from OpenMarket.
Simple text
This provides only the mobile operator code.
A successful (HTTP 200) simple text response option returns just the mobile operator code as text in the response body.
UK Example
TMOBILEUKUS Example
ATTUSAs well as the mobile operator code, there are two other values that may be returned:
- UNKNOWN — the mobile operator was unrecognised. Please contact us to extend coverage.
- FAILURE — the lookup failed.
Requests that fail (HTTP 400-499) return the word FAILURE in the response body.
Extended text
The extended text option returns the following information in a successful (HTTP 200) request:
| Parameter |
Description |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
msisdn |
The MSISDN that the response relates to. Returned: Always |
|||||||||
|
network |
The mobile operator of the MSISDN. If the MSISDN is connected via an MVNO, then this will be the mother mobile operator. Returned: Always |
|||||||||
|
network_code |
The MCC/MNC (mobile country code / mobile network code) or OCN (operating company number). If neither of these identifiers are known then Returned: Always |
|||||||||
| certainty |
This represents how the mobile operator information was discovered, including whether there was a failure with retrieving the mobile operator details. Returned: Always Default: simple text |
|||||||||
|
||||||||||
| mvno |
The name of the mobile virtual network operator (MVNO) associated with the handset. Note that in some cases this information will not always be available; for example, if the mobile phone 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 an MVNO. Returned: Only if the end user is on an MVNO |
UK Example
msisdn: 447700900750network: TMOBILEUKnetwork_code: 23430certainty: 4US Example
msisdn: 12515550100network: ATTUSnetwork_code: 06010certainty: 4Failed requests:
| Parameter |
Description |
|---|---|
|
msisdn |
The MSISDN that the response relates to. Returned: Always |
|
error |
A text description of the error. Returned: Always |
UK Example
msisdn: 447700900750error: Authentication ErrorUS Example
msisdn: 12515550100error: Authentication ErrorXML response
The XML response option returns the following information in a successful (HTTP 200) request:
| Parameter |
Description |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
msisdn |
The MSISDN that the response relates to. Returned: Always |
|||||||||
|
network |
The mobile operator of the MSISDN. If the MSISDN is connected via an MVNO, then this will be the mother mobile operator. Returned: Always |
|||||||||
|
network_code |
The MCC/MNC (mobile country code / mobile network code) or OCN (operating company number). If neither of these identifiers are known then Returned: Always |
|||||||||
| certainty |
This represents how the mobile operator information was discovered, including whether there was a failure with retrieving the mobile operator details. Returned: Always Default: simple text |
|||||||||
|
||||||||||
| mvno |
The name of the mobile virtual network operator (MVNO) associated with the handset. Note that in some cases this information will not always be available; for example, if the mobile phone 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 an MVNO. Returned: Only if the end user is on an MVNO |
UK Example
<?xml version="1.0"?><response><msisdn>447700900750</msisdn>
<network>TMOBILEUK</network>
<network_code>23430</network_code>
<certainty>4</certainty>
</response>US Example
<?xml version="1.0"?><response><msisdn>12515550100</msisdn><network>ATTUS</network><network_code>06010</network_code><certainty>4</certainty></response>Failed requests:
When a request fails (HTTP 400-499), the XML response options can contain the following information:
| Parameter |
Description |
|---|---|
|
msisdn |
The MSISDN that the response relates to. Returned: Always |
|
error |
A text description of the error. Returned: Always |
UK Example
<?xml version="1.0"?><response><msisdn>447700900999</msisdn><error><message>Authentication Error</message></error></response>US Example
<?xml version="1.0"?><response><msisdn>1255550145</msisdn><error><message>Authentication Error</message></error></response>Unexpected characters in the response
If you receive unexpected characters in an HTTP response from OpenMarket, it may be because we are using "chunked" transfer coding, which is part of the HTTP 1.1 specification. These are normally stripped out by the browser or other transfer agent you are using. However, you may see these characters while connecting to OpenMarket via Telnet. You can ignore these characters if you see them.