API Reference

Overview

You'll find all of the API operations we offer documented here. Each operation has in-depth information on how to authenticate, the data you'll need to send, and troubleshooting information such as delivery receipt codes (and other response codes).

Supporting information for the messaging and operations is in Integration Basics.

Latest updates

For information about changes to operations and their behavior, see What's New.

When we improve an existing API, we'll always endeavor to make API changes such that they are backward compatible. For example, we if we add a new data field (e.g. attribute, element, or object), we won't change the overall structure or name of any existing data field. However, you should write your applications to ignore unknown data fields, so that your application continues to function as we improve our platform and you prepare to use new data fields.

Which SMS API should I integrate with?

If you're new to OpenMarket, you may be wondering what SMS API to integrate with. The short answer is our Global SMS API. This is a RESTful API that supports both JSON and XML operations. There are several enhancements that make it the best API to integrate with, including simple character encoding options, automated originator selection, and efficient tracking of multipart messages. These features and enhancements aim to simplify your own application. Lastly, we offer contractual SLA of 99.99% for the Global SMS API.

If you are already an OpenMarket customer and have integrated with our version 3 SMS HTTP API, you may continue to use it, though we urge customers to consider migrating as the new capabilities will not be back-ported to version 3.

We also offer an SMPP API, which has the same features as our version 3 SMS HTTP API. We recommend using SMPP only if you have a previous integration using SMPP, as integrating with SMPP is more complex than with our HTTP APIs.

All of our SMS APIs are highly available, geo-redundant, and offer high throughput.

Connecting to OpenMarket

When connecting to OpenMarket, we strongly recommend using HTTPS connections over secure port 443.

While HTTP over port 80 is available, your data (and potentially your end user’s information) is sent in plain text, which a third party could intercept and read.

Our SMS and MMS endpoints support versions 1.0, 1.1, and 1.2 of Transport Layer Security (TLS).

Basic authentication

The majority of our operations use Basic authentication in the request header.

To use Basic authentication, you'll need to base64 encode your OpenMarket account ID and password. You must encode it in the format accountid:password. For example:

abcAccountId:123Password

Looks like this when encoded:

YWJjQWNjb3VudElkOjEyM1Bhc3N3b3Jk

In the header, specify "Authorization: Basic" and then your encoded details. For example:

Authorization: Basic YWJjQWNjb3VudElkOjEyM1Bhc3N3b3Jk

If your account ID was "123-123-123-12345", and your password was "Secure123", then you would encode "123-123-123-12345:Secure123". In the header this would look like:

Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Your account ID and password are both case-sensitive.

Setting your own identifiers in a request

You may want to send your own identifiers with a message request, such as your own ticket or transaction IDs, or campaign and program names. We offer two fields in our Global SMS API for this: note1 and note2.

These values appears in the SMS Detailed Data Source and MAR Detailed reports, and are returned in delivery receipts.

Formatting phone numbers

In your message requests to OpenMarket, you must include the country calling code (or dial in code) with the end user's phone number. For example:

  • US numbers must include "1" at the start: 12125550123
  • UK numbers must include "44" at the start: 447700900750
  • Uzbekistan numbers must include "998" at the start: 998901234567

These codes are defined in the ITU-T standards E.123 and E.164, and are also available on Wikipedia.

Your text-enabled virtual mobile number (VMN), toll-free number, or landline number must also use this format in the source address. Do not include a "+" character with a number.

Responses and requests from OpenMarket will also use this format for phone numbers.

Response from OpenMarket

We'll always provide a synchronous response to your requests, indicating whether the request was accepted or rejected.

We use standard HTTP status codes to indicate whether a request was successful. As well as the HTTP status codes, OpenMarket returns are own response codes, which you can find documented on each operation's page.

HTTP code

Description

200-299

Indicates that the request was accepted.

However, even if a request is accepted, there might be in issue with processing the request further.

400-499

Indicates that there was an issue with the request.

500-599

Indicates that there was a systems issue.

Identifiers returned by OpenMarket

Whenever you send a request, we'll respond with unique identifier so that you can match future reports and notifications. The primary ones are:

  • X Request ID — This identifies a request in OpenMarket's systems. Our SMS, MMS, and related operations all include this in the request header. This ID is useful when you need to contact OpenMarket Support regarding a specific transaction.
  • Ticket ID (SMS)  — This identifies an accepted SMS message request. If your message is split into multiple parts, they will share the same ticket ID in your delivery receipts. Ticket IDs are also used to identify MO messages.
  • MT ID and MO ID (MMS) — These identify accepted MMS message and MO MMS messages, respectively.

Other operations return additional unique IDs as required.

Accepting asynchronous message and notifications from OpenMarket

When you provision a messaging account with us, make sure you provide us with a default URL for receiving message requests and other types of requests from OpenMarket.

To ensure the authenticity of requests, you should only accept requests from the following OpenMarket IP addresses:

  • 83.166.64.0 - 83.166.67.255 (83.166.64.0/22)
  • 83.166.68.0 - 83.166.69.255 (83.166.68.0/23)
  • 83.166.72.0 - 83.166.75.255 (83.166.72.0/22)
  • 83.166.80.0 - 83.166.83.255 (83.166.80.0/22)
  • 208.93.48.0 - 208.93.51.255 (208.93.48.0/22)

What if I can't seem to receive a request?

If you do not receive requests from us to an HTTPS URL, but you can receive them over standard HTTP, a possible cause is that we do not recognize and trust your server's security certificate. You must obtain an additional certificate from one of the trusted certification authorities.