Request Differences

This page explains the main differences between UK SMS API requests and Global SMS API requests.

If you're currently using our UK SMS API (also known as the MX API), then this information is for you. If you're new to OpenMarket, see the Overview to find out how to connect to us.

Available operations

The Global SMS API is RESTful and offers a Get Message Status operation which is not available with the UK SMS API.

New terms to know

Destination

Destination is similar to smsto; e.g. it provides details about the message recipient.

Interaction

Interaction identifies whether your messaging is one-way or two-way. You can set interaction in an MT message request if you want OpenMarket to select the message originator for you. See also Automated Originator Selection and Message originators.

Message originators

This is our term for the text-able numbers (or alphanumeric strings) you use to send and receive messages.

Mobile operators

We use the term "mobile operator" to refer to the mobile carriers and networks. However, you may still see the term "carrier" sometimes used.

In the API and in Reporting Insights, we use a numerical code to represent the mobile operator. Network Codes (UK SMS) shows what the number is for each MX network code. The more general page, Mobile Operator IDs, provides a list of the mobile operator names and IDs for these regions: UK, US, Canada, Ireland and Australia; and what messaging options each operator supports.

note1 and note2

These are free-text fields that act in a similar way to note. They are included in detailed reports but not in summary reports.

Promotional

This relates to India messaging only. When messaging in India, you must identify your message as promotional if your message is for a marketing or promotional use case.

Source

Source is similar to smsfrom; e.g. it is details about the message sender.

Ticket ID

A ticket ID is synonymous with smsid. It does not refer to a ticket raised with OpenMarket Support.

Sending an SMS

Note: The examples in this release note use JSON. You also have the option to integrate using XML; however, we recommend using JSON as it's simpler to read and parse.

The Send an SMS operation uses POST, rather than GET, to send an SMS. The request header has your authentication details, while the request body contains everything required to send the SMS message.

The URL for requests is:

POST https://smsc.openmarket.com:443/sms/v4/mt

There are no URL parameters.

Header

You must include your authentication details in the header using Basic authentication. This requires you to format the account ID and password as "accountid:password", then base-64 encode the string. To begin using the Global SMS API, you will need to get a new account ID, rather than use an existing ID.

You'll also need to include the "Content-Type" in the header. This lets us know that the request body uses either XML or JSON. We'll reply in the same format.

1
2
3
4
POST /sms/v4/mt HTTP/1.1
Host: smsc.openmarket.com
Content-Type: application/json; charset=UTF-8
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Request body

The request body contains the details for your message.

This example JSON request includes most of the objects and name-value pairs you can include to send a plain text message. However, many of these are optional and may not be relevant to your messaging. The table below will explain the new terms.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
   "mobileTerminate": {
      "interaction": "two-way",
      "promotional": "false",
      "options": {
         "note1": "My high-level campaign or messaging service name",
         "note2": "My Internal ID",
         "programId": "1234",
         "flash": "false"
      },
      "destination": {
         "address": "12125550123",
         "mobileOperatorId": 383
      },
      "source": {
         "ton": 3,
         "address": "222111"
      },
      "message": {
         "content": "This is a text message!",
         "type": "text",
         "validityPeriod": 259200,
         "mlc": "segment"
      },
      "delivery": {
         "receiptRequested": "final",
         "url": "https://my.example.com/receiver.php"
      }
   }
}

mobileTerminate

interaction

promotional

note1 and note2

programId

"destination": {

"address": "12125550123",

"mobileOperatorId": 383

},

"source": {

"ton": 3,

"address": "222111"

},

"message": {

"content": "Hello!",

"type": "text",

"validityPeriod": 259200,

"mlc": "segment"

}

"delivery": {

"receiptRequested": "final",

"url": "https:my.example.com"

}

How to send comparable message requests

The following table explains how to do comparable tasks between the two APIs.

smsto=12125550123

"destination": {

"address": "12125550123",

"mobileOperatorId": 383

}

smsfrom=88600

"source": {

"ton": 3,

"address": "222111"

}

push_type=0

push_action={0,1,2,3,4}

push_href={url}

push_siname={name of service indication}

push_siid={delete only}

push_siexpires={expirytime}

push_initiator={alternate originator field}

"message": {

"type": "wapPush",

"content": "Click me",

"url": "https://www.example.com"

}

smsmsg=01020304

smsudh=06050412341234

"message": {

"type": "binary",

"content": "0741524745543a20506c",

"udh": true

}

mms_expire={}

mms_messageclass={}

mms_messagelocation={}

mms_messagesize={}

mms_notification={}

mms_transaction_id={}

mms_version={}

mms_from={}

mms_subject={}

smsudh=06050412341234

bits=7

"message": {

"type": "hexEncodedText",

"content": "54727573742...",

"udh": true

}

split={0,1,2,3}

"message": {

"mlc": "segment"

}

flash={0,1}

"options": {

"flash": "true"

}

report={0,1,2,3,4,5,6,7}

"delivery": {

"receiptRequested": "final",

"url": "https:my.example.com/rec.php"

}

subaccount={free text}

note={free text}

"options": {

"note1": "My Internal ID or text 1",

"note2": "My Internal ID or text 2"

}

vp={number}

"message": {...

"validityPeriod": 259200

}

"options": {

"programId": "1234"

}

response=text

response=legacytext

submitid={broadcastname}

Character sets and encodings

All requests to the Global SMS API must use UTF-8. Standardizing on UTF-8 ensures that it is simple to send MT message requests to any end user in any region, without having to consider whether you are sending the message content as GSM, Modified Latin-9 or Unicode UCS-2.

For MT message requests, we convert the message content to use the encoding that's optimal for the mobile operator. For many mobile operators and messages, we use GSM. However this is not the case if the mobile operator requires a different encoding or your message uses characters outside the GSM set.

If desired, however, you can send us the message content using another character encoding, one of: GSM, Latin-1, UTF-8, or UTF-16. We will still convert the message to the optimal format for the mobile operator. The message request must still use UTF-8.

Simple example

In this example, you can see the message content is "hello" and the type of message is "text" (this selects between text, hex-encoded text, WAP Push, and binary messaging).

1
2
3
4
5
6
7
8
9
10
11
12
{
   "mobileTerminate": {
      "message": {
         "type": "text",
         "content": "Hello"
      },
      "destination": {
         "address": "12515550145"
      }
   }
}

Example using specific character encoding

When sending a message using a specific encoding, you must hex-encode the message text. In this example, the message content is in UTF-16, and the type is "hexEncodedText".

1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "mobileTerminate": {
      "message": {
         "type": "hexEncodedText",
         "charset": "UTF-16",
         "content": "5472757374206E6F2D6F6E652E"
      },
      "destination": {
         "address": "447700900765"
      }
   }
}

OpenMarket's response

The synchronous response from the UK SMS API provides an SMS ID, or multiple SMS IDs if it is a multipart messages. The Global SMS API tracks your message request in a slightly different way. Our synchronous reply will tell you whether the request was accepted, but does not identify if your message needs multiple parts. This is because we need to check the message's character use against the mobile operator's constraints before we can process the message.

Responses use the same format (JSON or XML) as your message request.

Accepted requests

OpenMarket sends an HTTP 202 response if a request is accepted. For accepted message requests, the Global SMS API provides two tracking values:

• A location, where the last part of the location is a unique value that identifies your MT message. This is referred to as the ticket ID in OpenMarket systems. For multipart messages, each part of the message shares the same ticket ID.
• An X-Request-Id, which is a unique value that identifies each request, regardless of whether it was successful or not.

These are returned in the request header. There is no request body. In the example below, the ticket ID is 03155-0331L-1439U-51SLFX.

1
2
3
4
5
6
7
8
HTTP/1.1 202 Accepted..Server: Apache-Coyote/1.1
Location: https://smsc.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tue, 31 Mar 2015 18:39:51 GMT
Connection: close

Rejected requests

OpenMarket sends a standard HTTP 400-599 response if a request is rejected. The request header will contain an X-Request-Id, but not a Location as no resource was created. The body of the response will contain a code that identifies the error. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1
X-Request-Id: 001-1-761372B6-EE31-427E-AEB4-ED9E88CDD7A6
Content-Type: application/json;charset=UTF-8
Date: Tue, 13 Oct 2015 21:01:59 GMT
Connection: close
{
   "error": {
      "code": "540",
      "description": "Invalid request - destination address is required"
   }
}

You can find a full list of the error codes on the operation's page in our API reference: Response error codes.

Get Message Status operation

The Get Message Status operation does not have a parallel in the UK SMS API. This section describes the data returned by the Get Message Status operation, however, for full details on how to integrate, refer to the JSON or XML operations.

Making a request

Send a GET request to:

GET https://smsc.openmarket.com/sms/v4/mt/<ticket ID>/status

You need to provide the ticket ID of a message request, for example:

https://smsc.openmarket.com/sms/v4/mt/44101-0922I-13413-21GDL/status

You can find the ticket ID in the response from OpenMarket to a Send an SMS request. There are no other URL parameters.

Header

You must include your authentication details and the Accept field in the header, for example:

Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/json

Request body

There is no data required in the request body.

Response from OpenMarket

If your request is accepted then OpenMarket sends an HTTP 200 response with the details of the message status in the request body. For a list of delivery receipt code and description values, see Delivery Receipts and Response Codes.

The following example request is for a single part message, and contains all the possible name-value pairs you could receive. However, please note that some of these pairs are not always included in a response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
HTTP/1.1 200 OK
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8
{
   "mtStatus": {
      "ticketId": "03155-0331L-1439U-51SLFX",
      "code": "4",
      "description": "Message delivered",
      "deliveryDate": "2015-12-01T20:04:18.000Z",
      "note1": "My Internal ID or text 1",
      "mobileOperatorId": 386,
      "destination": {
         "address": "14255550100",
         "mobileOperatorId": 386,
         "alpha2Code": "US"
      },
      "source": {
         "ton": 1,
         "address": "12345520000"
      }
   }
}

The following example contains the possible name-value pairs you would receive for a multipart message. In the mtStatus object, code and description provide an overall status for the multipart message. Each part is given a segment number as well as it's own delivery receipt code and description.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
   "mtStatus": {
      "ticketId": "03155-0331L-1439U-51SLFX",
      "code": "831",
      "description": "Awaiting complete message delivery status",
      "note1": "My Internal ID or text 1",
      "totalSegments": 2,
      "destination": {
         "address": "32255550100",
         "alpha2Code": "BE"
      },
      "source": {
         "ton": 5,
         "address": "ABDCEF"
      },
      {
         "segments":[
            {
               "segmentNumber": 1,
               "deliveryDate": "2015-10-06T22:34:17Z",
               "code": "4",
               "description": "Message delivered"
            },
            {
               "segmentNumber": 2,
               "code": "3",
               "description": "Message accepted by mobile operator. Awaiting receipt"
            }
         ]
      }
   }
}

For a description of the values, refer to the JSON or XML operation.

Receive a Delivery Receipt

Delivery receipts from the Global SMS API provide more data than the UK SMS API, such as the mobile operator (for US messaging), the delivery date, a description of the delivery status, and the ability to track multipart messages.

You will receive a delivery receipt for each part of a multipart message. This operation and the Get Message Status operation share the same delivery receipt code and description values.

The Global SMS API sends delivery receipts using POST.

Request header

The request header from OpenMarket will look similar to the following:

1
2
3
4
5
6
7
POST / HTTP/1.1
User-Agent: OpenMarket
X-API-Version: 4
Host: smsc.openmarket.com
Content-Type: application/json; charset=UTF-8
Content-Length: 424
Connection: close

The X-API-Version identifies that this is version 4 of this specific API.

The Content-Type identifies that the request body is either in JSON or XML. The request body will use the same format (XML or JSON) that you used for the original message request.

Request body

The request body contains your message delivery status. The following example contains the possible name-value pairs you would receive for one part of a multipart message. Each part is given a segment number (starting from 1). The code and description provides the final delivery status.

For a list of delivery receipt code and description values, see Delivery Receipts and Response Codes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
   "deliveryReceipt": {
      "mtStatus": {
         "ticketId": "01111-12013-1604Y-18MRN",
         "deliveryDate": "2015-12-01T20:04:18.000Z",
         "code": "0",
         "description": "Message successfully sent to mobile operator",
         "mobileOperatorId": 383,
         "note1": "My Internal ID or text 1",
         "note2": "My Internal ID or text 2",
         "segmentNumber": 1,
         "totalSegments": 2,
         "destination": {
            "address": "12515550123",
            "mobileOperatorId": 383,
            "alpha2Code": "US"
         },
         "source": {
            "ton" : 3,
            "address": "222111"
         }
      },
      "type": "final"
   }
}

Responding to the request

When you receive an OpenMarket delivery receipt, return an HTTP 200 response with an empty response body.

If there are any errors receiving a delivery receipt, please use standard HTTP error response codes.

Mobile Operator Lookup

Compared to the UK Operator Lookup API, this operation (offered as part of the Global SMS API) provides more information about the mobile operator's capabilities. It also confirms details about the phone number.

Key differences are:

• The response format can be either XML or JSON. Plain text is not available.
• This operation provides only an "extended" response. A "simple" option that returns just the mobile operator is not available.
• This operation reports on the message length that the mobile operator accepts for single part messages. These are textLength (number of GSM characters) unicodeLength (number of UCS-2 characters) and binaryLength (number of bytes in a data message). Note that OpenMarket will use the most appropriate character encoding for your message for that operator, and this may be another available encoding.
• There is no "certainty" returned, as OpenMarket performs a lookup each time. If there is an issue with performing the lookup, such as the mobile number not being valid, we will return an error code.
• There is no "mvno" returned.
• The mobile operator names and IDs do not use the MX Telecom network codes. Network Codes (UK SMS) shows what the mobile operator ID is for each MX network code. For a list of what each operator supports in these regions: UK, US, Canada, Ireland and Australia, see Mobile Operator IDs.

Making a request

You need to send a GET request to:

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

You need to provide the phone number in the URL in international format, for example:

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

There are no other URL parameters.

Header

You must include your authentication details and the Accept field in the header, for example:

Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/json

Request body

There is no data required in the request body.

Response from OpenMarket

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 JSON example contains all possible name-value pairs. However, please note that some of these are not included in the response unless necessary:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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",
         "wireless": true
      },
      "mobileOperator": {
         "mobileOperatorId": 474,
         "mobileOperatorName": "Three",
         "textLength": 160,
         "binaryLength": 140,
         "unicodeLength": 70,
         "wapPush": true
      }
   }
}

For a description of the values, refer to the JSON or XML operation.

Receive an SMS

Mobile originated (MO) messages are sent using POST, and use the same terminology and general format as an MT request to the Global SMS API.

When migrating to this API, you will need to let OpenMarket Support know at what date you wish to start receiving MOs through this API. You will also need to tell Support:

• The URL to which you want us to send MOs
• What format (XML or JSON) you want MOs in
• Any Basic authentication details you wish us to use

Content types

OpenMarket forwards the MO SMS message as:

• Plain text — When the content is UTF-8 and doesn't contain any unusual characters.
• Hexadecimal-encoded text — When it is a multipart message, the content contains control characters such as carriage returns, or there is a user data header (UDH).
• Binary data — When we have received a binary message from the mobile operator. You must convert the message from its hex-encoded format into a usable string.

Multipart MO messages

If you are sent a multipart message, we forward each part of the message separately. The request will use hexadecimal-encoded text and each part will include a UDH that is at the start of each part's content.

Depending on the mobile phone and mobile operator, the UDH for multipart messages can differ to use either a 1-octet or 2-octet message reference. There might also be other headers included with the message. However, by far the most common UDH we receive for multipart messages is the 1-octet version, without additional headers. This uses 6 bytes (two characters in the hexadecimal message format), similar to "05 00 03 44 02 01". When you decode the UDH:

• Byte 1: Defines the number of bytes in the UDH (excluding itself). In the example, this is "05", indicating there are five bytes in the UDH following the first byte.
• Byte 2: Defines the type of message you have been sent. "00" means it is a multipart message.
• Byte 3: Similar to byte 1. Defines how many bytes remain in the rest of the UDH. In the example, this is "03".
• Byte 4: Contains a reference number. The value will be the same for each part of the multipart message.
• Byte 5: Provides the number of parts used to send the multipart message. For example, "02" means the multipart message is made of two parts.
• Byte 6: Identifies the message part. The numbering begins at "01".

Request header

The request header from OpenMarket will look similar to the following:

1
2
3
4
5
6
7
POST / HTTP/1.1
User-Agent: OpenMarket
X-API-Version: 4
Host: smsc.openmarket.com
Content-Type: application/json; charset=UTF-8
Content-Length: 424
Connection: close

The X-API-Version identifies that this is version 4 of this specific API.

The Content-Type identifies that the request body is either in JSON or XML.

Request body

Example where the message is from a UK end user, and is sent as plain text:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "mobileOriginate": {
      "submittedDate": "2015-08-29T15:10:03.029-05:00",
      "ticketId": "8514F-01278-17445-23FSJ",
      "source": {
         "ton": 1,
         "address": "447700900999"
      },
      "destination": {
         "ton": 3,
         "address": "58870"
      },
      "message": {
         "type": "text",
         "content": "I wish to register a complaint"
      }
   }
}

Example where the message is from a US end user, and is sent as hexadecimal-encoded text:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
   "mobileOriginate": {
      "submittedDate": "2015-08-29T15:10:03.029-05:00",
      "ticketId": "8514F-01278-17445-23FSJ",
      "source": {
         "ton": 1,
         "address": "12515550145",
         "mobileOperatorId": 383
      },
      "destination": {
         "ton": 3,
         "address": "222111"
      },
      "message": {
         "type": "hexEncodedText",
         "content": "050003080202207468696e6b696e672061626f75742069742e",
         "udh": "true"
      }
   }
}

mobileOriginate

submittedDate

ticketId

programId

"source": {

"ton": 1,

"address": "12515550145",

"mobileOperatorId": 383

}

"destination": {

"ton": 3,

"address": "222111"

}

"message": {

"content": "Hello!",

"type": "text"

}

Responding to the request

When you receive an OpenMarket delivery receipt, return an HTTP 200 or 201 response with an empty response body.

If there are any errors receiving a delivery receipt, please use standard HTTP error response codes.