HTTP Global SMS API

Mobile Operator Lookup

Use this operation to look up the mobile operator that services the mobile phone number. This operation returns the mobile operator ID and name, and this information about the operator:

The maximum number of GSM characters allowed in a single part message
The maximum number of bytes allowed in a single part message
The maximum number of UCS-2 characters allowed in a single part message
Whether the mobile operator supports WAP Push messaging
The maximum number of UCS-2 characters allowed in a single part message

Important: Depending on your contract with OpenMarket, you may be charged for operator lookup 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.

Click here to try

Make a request using the following sample cURL. You'll need to:

Replace the accountid:password with your OpenMarket account ID and password
Replace "0123456789" with the mobile number for which you wish to perform an operator lookup

curl -s -D - -X GET  -H "Accept: application/xml" --user accountid:password https://preview.openmarket.com/sms/v4/preview/0123456789

Response from OpenMarket

For successful requests, OpenMarket sends an HTTP 200 response. The header contains an X-Request-Id, while the response body contains the lookup data.

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="1" alpha2code="US" phoneNumber="12125550123" />
   <operator mobileOperatorId="383" mobileOperatorName="AT&T" textLength="160" binaryLength="140" unicodeLength="70" wapPush="true"/>
</preview>

Making a Request

Definition

GET https://preview.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://preview.openmarket.com/sms/v4/preview/447700900765

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

There are no other URL parameters for this endpoint.

This endpoint supports version Transport Layer Security (TLS) 1.2.

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 Authenticate with OpenMarket. Required: always
Accept	Specify application/xml for this request. Required: always

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 Authenticate with OpenMarket.

Required: always

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

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

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

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

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

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.