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

JSON

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

Your OpenMarket account must be provisioned to use this SMS product.

More information

See Overview.

Try It Out

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

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 you wish to look up
curl -s -D - -X GET  -H "Accept: application/json" --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/json;charset=UTF-8

{
   "preview": {
      "destination": {
         "countryCode": "1",
         "phoneNumber": "12125550123",
         "alpha2Code": "US" 
      },
      "mobileOperator": {
         "mobileOperatorId": 383,
         "mobileOperatorName": "AT&T",
         "textLength": 160,
         "binaryLength": 140,
         "unicodeLength": 70,
         "wapPush": true
      }
   }
}

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

Provide your authentication details using Basic authentication in the header.

Example header

Accept: application/json 
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/json for this request.

Required: always

Request body

No data is required in the request body.

Response from OpenMarket

Accepted requests

Once we accept your request, we send an HTTP 200 response with the details of the operator lookup in the request body.

The following JSON example contains all possible name-value pairs. Note however 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/json;charset=UTF-8

{
   "preview": {
      "destination": {
         "countryCode": "44",
         "phoneNumber": "447700900765",
         "alpha2Code": "GB"
      },
      "mobileOperator": {
         "mobileOperatorId": 474,
         "mobileOperatorName": "Three",
         "textLength": 160,
         "binaryLength": 140,
         "unicodeLength": 70,
         "wapPush": true
      }
   }
}

Response header

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 JSON in the request body.

Returned: always

Response body

The JSON body has a top-level object that contains the one member, preview.

Multiples of the same object will not occur.

destination object

Object that contains information about the phone number.

This object is not always returned.

Member

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 object

Object that contains information about the mobile operator.

This object is not always returned.

Member

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 we reject your request 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/json;charset=UTF-8
Date: Tue, 29 Sep 2015 17:54:39 GMT
Connection: close

{ 
   "error" : {
      "code":"420", 
      "description":"Invalid account ID or account password"
   }
}

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

JSON 

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 for rejected requests

Type: string

description

Description of the error.

Returned: always for rejected requests

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.