Introduction

• Table of Contents
• Formatting
  • JSON Formatting
  • Return Values
  • Error Response
  • Dates and Times
• Versions
• Authentication
  • API Keys
  • Authorization Header
• Enumerated Values
  • Automatic Winner Selection Metrics
  • Subscriber Statuses
  • Custom Field Types

This is the documentation for the SendSage Studio API. If you have
additional questions about the API, or feel that you’ve encountered a bug,
please don’t hesitate to contact us at
our support address.

Interactions with this API are accomplished over HTTP. On POST and PUT
requests, JSON is expected as the body of the request. All API calls reply with
JSON.

Formatting

JSON Formatting

The JSON included as examples in this document has been nicely formatted for
viewing. Neither the JSON expected as input into the API nor the JSON returned
by it will be formatted this way.

Return Values

All API requests will return a JSON hash with the following keys:

Error Response

Here’s an example of an error message returned by this API.

{
  "data": null,
  "error_code": "validation_failed",
  "error_message": "name cannot be blank",
  "success": false
}

Here are all of the error codes that Studio can return. See the error_message value for more information on the specific response.

Dates and Times

• Times are passed to the API in ISO 8601 date/time format:

  YYYY-MM-DDThh:mm:ss-ZZ:ZZ
  2013-03-27T10:41:15-05:00

• A date (with no time) can be passed to the API, and is returned, in the following format:

  YYYY-MM-DD
  2010-03-30

• Times are returned by the API as both an integer number of seconds since the
  UNIX epoch, and in ISO 8601 date/time format.

• All fields that are interpreted as a time also have a corresponding _epoch
  field with the integer number of seconds since the UNIX epoch. For example,
  on a subscriber the created_at field might have the value
  2013-03-27T10:41:15-05:00, there will also be a field created_at_epoch
  which contains the integer value 1364398875.

• The timezone of all times is the organization timezone.

Versions

During evolving the programmatic interface of API calls may change. To keep
things backward compatible, Studio uses API versioning. Each request you send
should explicitly specify the version of API you are targeting. There are two
ways to achieve that:

• You can specify version within request headers using the X-Version header.

  X-Version: 2

• You can specify version within request path using the path component v2.

  /ga/api/v2/campaigns

Important: for compatibility reasons you will be routed to version 1 if no version was specified!

Authentication

Every request to the SendSage Studio API must be authenticated. This is
done via the Authorization HTTP header in the request, as described below.

API Keys

Organization administrators may create API keys from their organization’s page.
To find that page, hover over Admin in the top navigation menu, then select
My Organization. See the API Keys section on that screen. The Key column
contains the value needed for authentication. The key will initially be
obscured behind a link; clicking reveal will display the key.

Authorization Header

The Authorization header must be included in every call to the SendSage Studio API.

Authorization: Basic <Data>

The <Data> portion of this header should be the Key value as shown after
clicking reveal on the Organization page.

Thus, for that example, our header would be the following.

Authorization: Basic MTowYTc0ZWQxM2ZjMTEyYTUwZTZkZjY3NDc5MDcyZjdiZDJiNDg1YzI1

Enumerated Values

Automatic Winner Selection Metrics

Subscriber Statuses

Custom Field Types