HTTP Global SMS API

Mobile Operator Lookup

Use this operation to find out the mobile operator that supplies services to the mobile number. This operation will also return information about what messaging the mobile operator supports.

Depending on your contract with OpenMarket, you may be charged for each of these requests.

Quick facts

Method

GET

Returns

XML

Available

Australia, Canada, the United States, the United Kingdom.

If a phone number is from outside of these regions, we return a 345 status code.

Prerequisites

You must have SMS messaging provisioned with OpenMarket.

More information

See Overview.

XML schema

You can download the schema for our XML requests (.zip file).

Try It Out

Once you're provisioned with an OpenMarket account, you can try out the operation using cURL.

Making a Request

Definition

GET https://smsc.openmarket.com/sms/v4/preview/<phone number>

You will need to provide the mobile number in an international format, that includes the country code but not a "+" character, for example (UK and US):

https://smsc.openmarket.com/sms/v4/preview/447700900765
https://smsc.openmarket.com/sms/v4/preview/12515550123

There are no other URL parameters for this endpoint.

This endpoint supports versions Transport Layer Security (TLS) 1.2 and 1.1.

Header fields

You must provide your authentication details using Basic authentication in the header.

Example header

Accept: application/xml 
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Field

Description

Authorization

Your account ID and password, separated by a colon, and then base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticating with OpenMarket.

Required: always

Accept

Specify application/xml for this request.

Required: always

Request body

There is no data required in the request body.

Response from OpenMarket

Accepted requests

If your request is accepted then OpenMarket sends an HTTP 200 response with the details of the operator lookup in the request body.

The following XML example contains all possible elements and attributes. However, please note that some of these are not included in the response unless necessary.

HTTP/1.1 200 OK
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/xml;charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<preview xmlns="http://sms.openmarket.com/v4/preview">
   <destination countryCode="44" alpha2code="GB" phoneNumber="447700900750" />
   <mobileOperator mobileOperatorId="474" mobileOperatorName="Three" textLength="160" binaryLength="140" unicodeLength="70" wapPush="true"/>
</preview>

Response header

The response header will include following data.

Field

Description

X-Request-Id

A unique ID that identifies the specific request you made in OpenMarket's systems.

This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date.

Returned: always

Type: case-insensitive string up to 45 characters in length

Content-Type

Identifies that the request contains XML in the request body.

Returned: always

Response body

The body has a top-level element, preview.

Multiples of the same element will not occur.

preview element

This element is always returned.

Attribute

Description

xmlns

The XML namespace:

http://sms.openmarket.com/v4/preview

Returned: always

Type: string

destination element

Element that contains information about the phone number.

This element is not always returned.

Attribute

Description

countryCode

The country dial in code for the phone number. For example:

  • 44 — United Kingdom including Northern Ireland
  • 353 — Ireland
  • 1 — United States
  • 91 — India
  • 61 — Australia

Returned: always

Type: string

phoneNumber

The phone number of the end user, including the country code.

Returned: always

Type: string, up to 20 characters long.

alpha2Code

Identifies the country of origin for the phone number. This is a two-letter country code, as defined in ISO 3166-1. For example:

  • GB — United Kingdom including Northern Ireland
  • IE — Ireland
  • US — United States
  • IN — India
  • AU — Australia

Returned: always

Type: string

mobileOperator element

Element that contains information about the mobile operator.

This object is not always returned.

Attribute

Description

mobileOperatorId

An OpenMarket-specific number that identifies the mobile operator.

For a list of the valid IDs, see Mobile Operator IDs.

Returned: always

Type: integer

mobileOperatorName

The name of the mobile operator.

Returned: if known

Type: string

textLength

The maximum number of GSM characters that you can send in a single part message to this operator.

Returned: if known

Type: integer

binaryLength

The maximum number of bytes that you can send in a single part message to this operator.

Returned: if known

Type: integer

unicodeLength

The maximum number of UCS-2 characters that you can send in a single part message to this operator.

Returned:if known

Type: integer

wapPush

Whether the mobile operator supports WAP Push messaging. Either:

  • true — Supports WAP Push
  • false — Does not support WAP Push

Returned: if known

Default: true

Type: Boolean

Rejected requests

If your request is rejected then the body of the response will contain a code that identifies the error. For example:

HTTP/1.1 401 Unauthorized
Server: Apache-Coyote/1.1
X-Request-Id: 001-72-351B8F7C-59C1-420B-8A9A-59D20D93ED85
Content-Length: 82
Content-Type: application/xml;charset=UTF-8
Date: Tue, 29 Sep 2015 17:54:39 GMT
Connection: close

<?xml version="1.0"? encoding="UTF-8" standalone="yes"?>
<error code="420" description="Invalid Account ID or account password" xmlns="http://sms.openmarket.com/v4/preview" />

Header fields

Field

Description

X-Request-Id

A unique ID that identifies the specific request you made in OpenMarket's systems.

This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date.

Returned: always

Type: case-insensitive string up to 45 characters in length

Response body

The response body will contain one element, error.

Attribute

Description

code

Code defining the reason for the outcome of the request. For a list of the codes, see Response error codes below.

Returned: always

Type: string

description

Description of the error.

Returned: always

Type: string

xmlns

The XML namespace.

Returned: always

Type: string

Testing your integration

You can use the OpenMarket Customer Integration Environment (CIE) to test your integration. See Testing your integration with OpenMarket.

Troubleshooting

Response error codes

If there is a problem with the request, you will receive one of these codes in the response body.

HTTP 400-499 codes

OpenMarket error code

Error description

Notes

345

Mobile operator not found for the destination address

 

OpenMarket performed an operator lookup for the end user's number and found that the number is not registered with any mobile operators.

Note that the region in which we perform the lookup will depend on your messaging — if you are only provisioned for US and Canadian messaging then we will only perform an operator lookup with the US and Canadian mobile operators. Therefore, requests to mobile numbers based in other destinations (like the UK) would come back with this error.

420

Invalid account ID or account password

The authentication details you sent in the requests do not match, or do not exist. Check that your account ID and password are base 64-encoded, and have a colon between them; e.g.:

123-123-123-12345:Secure123

Encodes to:

MTIzLTEyMy0xMjMtMTIzNDU6U2VjdXJlMTIz

431

Account not provisioned for SMS

We recognized your account, but it is not provisioned for SMS messaging.

Talk to your OpenMarket account manager to provision SMS messaging.

432

Account blocked for SMS

Your OpenMarket account is blocked from using this operation.

Talk to your OpenMarket account manager for more information.

433

Account not provisioned for operator lookups

Your OpenMarket account has not been provisioned to use this operation. Talk to your OpenMarket account manager to provision.

540

Invalid request - phone number is invalid

The phone number is not appear to be a phone number. For example, this is returned if the number:

  • Has a "+" character at the front
  • Includes any other non-digit character
  • Is too short or too long for a phone number

HTTP 500-599 codes

OpenMarket error code

Error description

Notes

1000

Temporary error processing request

This error is returned when OpenMarket is temporarily unable to process requests. Retry your request in intervals of 10 seconds or more, and contact OpenMarket Support if you continue to receive this error.

1010

Temporary system error

This error is returned when OpenMarket is temporarily unable to process requests. Retry your request in intervals of 10 seconds or more, and contact OpenMarket Support if you continue to receive this error.