HTTP Global SMS API

Request Differences Between v3 and v4

This page covers the new and removed XML elements/attributes between our v3 SMS API and our Global (v4) SMS API.

If you're currently using our v3 API, then this information is for you. If you're new to OpenMarket, see the Overview to find out how to connect to us.

Changes to terms used

The Global SMS API includes some new conceptual terms and changes to the terms we use in requests.

New terms:

Message originators —This is our term for the text-able numbers (or alphanumeric strings) you use to send and receive messages.
Interaction — Interactions identifies whether your messaging is one-way or two-way.
Mobile operators — We have changed from using the term "carrier" to "mobile operator". This term is better understood globally.

Terms with altered meanings:

type — This no longer refers to the type of request. Instead, it identifies whether the message is text, hexadecimal-encoded text, binary, or WAP Push.

We no longer use the following terms:

charge types — You do not need to include a charge type in your message requests. However, OpenMarket reporting will continue to use this naming in the short term.
text and data — In MT and MO requests, the content of the message is no longer identified using text or data. This is now identified using content.
purpose — A new term, promotional, replaces purpose.

Mobile Terminate (MT) message requests

Definition

The endpoint for v4 message requests is:

Copy

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

There are no URL parameters for this endpoint.

Header fields

All v4 requests require you to provide your authentication details in the header, in the following format:

Copy

Authorization: Basic <base64-encoded accountid:password>

The header also needs to include Content-Type: application/xml.

Copy

Example Header

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

Body

We have improved this in v4 to remove elements and attributes that are no longer needed, as well as rename some existing attributes, and add some new elements and attributes.

An example MT request, including most of the possible attributes is:

Copy

1
2
3
4
5
6
7
8
9
10
11
<?xml version="1.0" encoding="UTF-8"?>
<mobileTerminate interaction="one-way" promotional="false">
   <options note1="My Internal ID or text 1" note2="My Internal ID or text 2" programId="1234" flash="true" />
   <destination address="12125550123" mobileOperatorId="383" />
   <source ton="3" address="222111" />
   <message type="text" mlc="segment" validityPeriod="259200">
      <content>This is a text message!</content>
   </message>
   <delivery receiptRequested="final" url="https:my.example.com/receiver.php" />
</mobileTerminate>

Removed elements

request
<request version="3.0" protocol="wmp" type="submit" retryOfTicketId="00000-01234-1805S-56789">	The request element and its attributes: version, protocol, type, and retryOfTicketId. This as been replaced with a new root element, mobileTerminate.
user
<user agent="XML/SMS/1.0.0" />	This information is not needed, so no parallel exists in v4.
account
<account id="123-456-789-12345" password="your password" />	The account element and its attributes: id and password. Your authentication details are now provided in the request header.

New elements

mobileTerminate
<mobileTerminate interaction="one-way" promotional="false"> . . . </mobileTerminate>	mobileTerminate, a root level element, that containing the attributes: interaction — this replaces the charge_type attribute. promotional — this replaces the purpose attribute.
content (child of message)
<message type="text"> <content>This is a text message! </content> </message>	The message element now has a child element, content, that contains either your text message or binary data. This replaces the text and data attributes.

Updated elements

option(s)
<options programId="1234" note1="My Internal ID or text 1" note2="My Internal ID or text 2" flash="true" />	The option element is now named options. Changes to its attributes are: program_Id is now programId. note is now note1 and a new attribute, note2, exists to hold the same type of values. A new attribute, flash, lets you send a flash message. type, mlc, datacoding and url attributes were removed; similar attributes now exist in the message element. charge_type and purpose were removed. Similar attributes (interaction and promotional) exist in the new mobileTerminate element.
destination
<destination address="12125550123" mobileOperatorId="383" />	In the destination element, changes to the attributes are: ton is removed. This means the address must always include the country code, and must not include a "+" character. carrier was renamed to mobileOperatorId.
source
<source ton="3" address="222111" />	There are no changes to the attributes inside the source element. However: The source element is now optional. If specified, you must include source address. ton is now optional
message
<message type="hexEncodedText" mlc="segment" validityPeriod="10000" udh="true" charset="GSM"> <content>303530303...</content> </message>	The message element now has a child element, content. There are also changes to the attributes for message: A new attribute, type, identifies whether the message content is plain text, hexadecimal-encoded text, a WAP Push, or binary data. The mlc attribute is now part of the message element. The values are now: segment, truncate, and reject. validity_period is now validityPeriod. udhi is now udh. A new attribute, charset, identifies the character encoding you have used if you send hexadecimal-encoded text. The text and data attributes were removed. These have been replaced by the new content element.
delivery
<delivery receiptRequested="final" url="https:my.example.com/receiver.php" />	In the delivery element, the attribute receipt_requested has been replaced with receiptRequested. You can set this to the value: final.

Response from OpenMarket

Ticket IDs are no longer included in the response body. Instead, successful MT requests include a Location in the header, where the last part of the path is the ticket ID:

Copy

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

For example:

Copy

Location: https://smsc.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX

Note that multipart messages are identified using two ticket IDs in each part; the original ticket ID is called the Parent Ticket ID.

Accepted response

With v4, accepted responses do not have a request body. OpenMarket sends an HTTP 202 response, with an X-Request-Id and Location in the response header. The X-Request-Id identifies the request you made.

Copy

1
2
3
4
5
6
7
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/xml;charset=UTF-8
Content-Length: 0
Date: Tue, 31 Mar 2015 18:39:51 GMT
Connection: close

Rejected response

OpenMarket sends an HTTP 400-599 code for rejected requests. In the response body, an error code and description provide information about the issue. Rejected requests no longer include the resolution attribute.

The request header includes an X-Request-Id, but not a Location as no resource was created.

Copy

1
2
3
4
5
6
7
8
9
HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1
X-Request-Id: 001-1-41FE2D40-32D1-4D62-8479-42BA384C617A
Content-Type: application/xml;charset=UTF-8
Date: Tue, 13 Oct 2015 20:58:52 GMT
Connection: close

<?xml version="1.0"encoding="UTF-8" standalone="yes"?>
<error description="Invalid request - destination address is required" code="540" />

Get Message Status (Query) requests

Key changes include:

This is a GET request, rather than a POST
For messages split into multiple parts, the response will include information about each part.
Returns the mobile operator ID (previously called carrier ID), if known, as well as additional data such as the delivery date.

Definition

Send your GET requests to the following URL:

Copy

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

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

Copy

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

Header fields

All v4 requests require you to provide your authentication details in the header, in the following format:

Copy

Authorization: Basic <base64-encoded accountid:password>

The header also needs to include Accept: application/xml.

Copy

Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/xml

Accepted response

OpenMarket sends an HTTP 200 response, with the X-Request-Id and Content-Type fields in the response header.

Copy

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

For multipart messages, we return the delivery status for each part in the same response. You will receive data about each part, including an individual receipt code and description, and you will also receive a summary receipt code and description. This code will help indicate the current status of the entire message:

Code 830, "Partial message delivery failure", means that at least one of the message parts was not successfully delivered.
Code 831, "Awaiting complete message delivery status", means that the mobile operator has not returned a delivery receipt for one or more of the message parts. For example, you will get this code if one message part was successfully delivered but we do not have a receipt for the second part. However, if any message part fails delivery, then code 830 is returned.

Any other code means that the result for all parts of the message is the same. For example, if it is a "success" code of 0 or 4 then all parts were successfully delivered; if it is the same code to indicate a problem then all parts experienced the same problem.

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

Copy

1
2
3
4
5
6
7
8
9
10
11
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" standalone="yes"?>
<mtStatus ticketId="01111-12013-1504Y-18K6Q" deliveryDate="2015-12-01T20:04:18.000Z" code="4" description="Message delivered" mobileOperatorId="383" note1="My Internal ID or text 1" xmlns="https://sms.openmarket.com/v4/mt">
   <destination mobileOperatorId="383" alpha2Code="US" address="14255550100"/>
   <source address="12345" ton="3"/>
</mtStatus>

The following example contains the possible elements and attributes you would receive for a multipart message.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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" standalone="yes"?>
<mtStatus ticketId="01111-12013-1504Z-19BLAH" totalSegments="2" note1="My Internal ID or text 1" mobileOperatorId="383" code="830" description="Partial message delivery failure" xmlns="https://sms.openmarket.com/v4/mt">
   <destination mobileOperatorId="383" alpha2Code="US" address="14255550100"/>
   <source address="12345" ton="3"/>
   <segments>
      <segment segmentNumber="1" deliveryDate="2015-12-01T20:04:18.000Z" code="4" description="Message delivered">
      </segment>
      <segment segmentNumber="2" code="811" description="Message expired before it reached handset" />
      </segment>
   </segments>
</mtStatus>

You can find a full description of the returned data on the page for the operation: Get Message Status.

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

Copy

<?xml version="1.0"? encoding="UTF-8" standalone="yes"?>
<error code="711" description="Ticket ID not found" />

Mobile Operator Lookup (Preview) requests

The response to a Get Operator (previously Preview) request contains only information that we identified as useful for customers. This reduces the amount of data sent. There is also new information — a wireless value in the response body indicates whether the number is a mobile or landline number. This is relevant for messaging US end users.

Definition

Send your GET requests to the following URL:

Copy

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

You will need to provide the phone number in an international format, that includes the country code but not a "+" character, for example:

Copy

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

Header fields

All v4 requests require you to provide your authentication details in the header, in the following format:

Copy

Authorization: Basic <base64-encoded accountid:password>

The header also needs to include Accept: application/xml.

Copy

Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/xml

Accepted response

OpenMarket sends an HTTP 200 response, with the X-Request-Id and Content-Type fields in the response header.

Copy

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

The response body contains the operator lookup information. There are two child elements:

destination provides information about the mobile number
mobileOperator provides information about the operator who provides services for the mobile number

Copy

1
2
3
4
5
6
<?xml version="1.0" encoding="UTF-8"?>
<preview >
   <destination countryCode="44" alpha2code="GB" phoneNumber="447700900750" wireless="true" />
   <mobileOperator mobileOperatorId="474" mobileOperatorName="Three" textLength="160" binaryLength="140" unicodeLength="70" wapPush="true"/>
</preview>

You can find a full description of the returned data on the page for the operation: Mobile Operator Lookup .

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

Copy

<?xml version="1.0"? encoding="UTF-8" standalone="yes"?>
<error code="420" description="Invalid Account ID or account password" />

Receive a Delivery Receipt

Improvements to delivery receipts are:

Messages split into multiple parts are easily tracked in delivery receipts. Each part of a multipart message will have a delivery receipt, with segmentNumber and totalSegments identifying the part.
The possible codes and IDs (response, state and reason) are reduced so that there is just one type of code.
The information sent in a delivery receipt and a Get Message Status response is the same for single part messages. For multipart messages, the Get Message Status response provides delivery receipt details for each part.
Includes the mobile operator ID, if known.

Request header

The request header includes two fields:

X-API-Version — Identifies that this request comes from v4 of our HTTP API.
Content-Type — Identifies that the request contains XML in the request body.

Copy

Example Header

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/xml; charset=UTF-8
Content-Length: 424
Connection: close

Request body

Version 4 delivery receipts have a request header and body similar to this example:

Copy

1
2
3
4
5
6
7
8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveryReceipt type="final" xmlns="https://sms.openmarket.com/v4/mt">
   <mtStatus ticketId="01111-12013-1504Y-18K6Q" deliveryDate="2015-12-01T20:04:18.000Z" segmentNumber="1" totalSegments="2" code="4" description="Message delivered" note1="My Internal ID or text 1" note2="My Internal ID or text 2" mobileOperatorId="383" /> 
   <destination address="12125550123" mobileOperatorId="383" alpha2code="US" />
   <source ton="3"address="222111" />
</deliveryReceipt>

Removed elements

response
<response description="Message successfully delivered." code="4"/>	The response element and its attributes have ben replaced with a new element, mtStatus.
message
<message deliveryDate="2012-04-02T18:01:14.293Z">...</message>	This message element has been removed. The deliveryDate attribute is now in the mtStatus element.
state
<state description="Delivered to destination address by carrier" id="5"/>	The state element and its attributes have been removed.
reason
<reason description="Message successfully delivered." code="4"/>	The reason element and its attributes have been removed.

New elements

response

<mtStatus ticketId="01111-12013..." deliveryDate="2015-12-01T20:04:18.000Z" segmentNumber="1" totalSegments="2" code="4" description="Message delivered" note1="My Internal ID or text 1" note2="My Internal ID or text 2" mobileOperatorId="383" />

The mtStatus element includes the ticketId and deliveryDate attributes, and introduces to delivery receipts these attributes:

segmentNumber and totalSegments — You will receive totalSegments and segmentNumber if the message was split into multiple parts. The segment number starts at "1".
code — The delivery receipt code.
description — The delivery receipt description.
note1 and note2 — Returned if you included these attributes in the MT request.
mobileOperatorId — A numeric ID that identifies the mobile operator (previously known as a carrier ID).

Receive an SMS request

The request header includes two fields:

X-API-Version — Identifies that this request comes from v4 of our HTTP API.
Content-Type — Identifies that the request contains XML in the request body.

Copy

Example Header

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/xml; charset=UTF-8
Content-Length: 424
Connection: close

Requests have a request header and body similar to this example:

Copy

1
2
3
4
5
6
7
8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mobileOriginate submittedDate="2015-12-25T06:02:18.123Z" ticketId="8514F-01278-17445-23FSJ"> 
   <source ton="1" address="12125550123" mobileOperatorId="383"/>
   <destination ton="3" address="222111" />
   <message type="hexEncodedText" udh="true" content="050003080202207468696e6b696e672061626f75742069742e" />
</mobileOriginate>

Removed elements

request
<request version="3.0" protocol="wmp" type="deliver">... </deliver>	The request element and its attributes have been replaced with a new element, mobileOriginate.
account
<account id="123-456-789-11111"/>	The account element and attributes has been removed. This information is not needed, so no parallel exists in v4.
option
<option datacoding="7bit" />	The option element has been removed. The datacoding attribute is no longer required. Requests are all in UTF-8.
ticket
<ticket id="0114E-0602R-2013F-27LQ0"/>	The ticket element has been removed. A similar attribute, ticketId now exist in the mobileOriginate element.

Updated elements

source
<source ton="1" address="12125550123" mobileOperatorId="383"/>	The attribute carrier is now mobileOperatorId. The possible values are still the same.
message
<message type="hexEncodedText" udh="true" content="050003080202207468696e6b696e672061626f75742069742e" />	The message element has the following changes: data is no longer an attribute. It is replace by content. content — The message sent to you, as either text, hexadecimal-encoded text, or binary content. type — A new attribute that identifies what type of message you have received. Possible values are text, hexEncodedText, and binary. udhi is now udh. This is still a Boolean value.

Response error codes

The response error codes returned with v4 differ from v3 in the following ways:

The code numbering has changed. For example, issues with the format or syntax of your request all use the new code 540.
We removed codes for attributes/elements that are not in v4.
We added new codes for attributes/elements that are new in v4.

You can find the list of possible error codes for each operation on the operation's page.

For delivery receipt codes, see Delivery Receipts and Response Codes.

Reports and activity search

The SMS MAR reports and activity search are the same for v4 and v3.

However, to support v4, the MAR reports and activity search includes two new charge types:

33 — enterprise one-way messaging
39 — enterprise two-way messaging

For US and Canada standard rate messaging, we will continue to use charge type 0.

One of the benefits of v4 is better multipart message tracking, including in the SMS activity search. Because each multipart message is given one ticket ID, when you enter the ticket ID in the activity search, we return all parts of a multipart message.