NAV
json

Vision6 REST API

Welcome to the Vision6 REST API documentation.

The REST API supports transactional methods that can be used to trigger time-sensitive and critical communications. Examples are welcome packs, invoices (as attachments), statements, payment confirmations and password resets.

This API has:

Getting Started

Prior knowledge of programming with REST APIs is recommended before using Vision6 REST API. If you need assistance with your integration, please contact our support team who can help with any technical questions. Full Vision6 documentation is also available at https://support.vision6.com.au.

To prepare for sending emails you will need:

Resources and Endpoints

Collections, instances and endpoints are used to explain how to use the REST API.

Collection

A collection is a paginated resource with zero or more instances.

Collections have pluralised names such as /v1/lists, /v1/messages and /v1/transactional-groups.

Instance

An instance is a representation of an entity in the product or a container for a set of related data.

Instances are located at a collection resource followed by an id and have singular names such as /v1/messages/7847, /v1/lists/14/contacts/497 and /v1/messages/45/content.

Endpoint

An endpoint can list or act upon a resource.

Authentication

HTTP Headers:

Authorization: Bearer NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyM

Authentication is required to ensure that platform data is secure for all requests. Bearer tokens are used to receive access tokens.

API Keys / Access Tokens

REST compatible API keys can be used as access tokens when sending requests. REST compatible API keys do not have expiry dates.

To validate that API keys are compatible with the REST API you can send a GET request to our endpoints. If a 200 response is received then the API key is valid.

OAuth 2.0 Scopes

We use OAuth 2.0 scopes to limit access to endpoints within the API. Scopes are not requested, but are determined by an API key's access level.

Without valid scopes certain requests will fail. You can view required scopes for each endpoint within this documentation.

Wildcards

Wildcard Replacement with JSON Contact Fields Sample:

Your invite code is <a href="https://example.com/?code=%%event_code%%">%%event_code%%</a>.

Your invite code is <a href="https://example.com/?code=SUMMER-FESTIVAL">SUMMER-FESTIVAL</a>.
{
    "email": "henry@example.com",
    "event_code": "SUMMER-FESTIVAL"
}

Wildcards allow for key/value replacements within text. Wildcards are used to insert personalised or dynamic content into the templates.

The format for wildcards is %%wildcard_key%%. Wildcard key characters are required to be lowercase, alphanumeric or underscores.

Values that accept wildcards are:

Fallback Text

Wildcard Fallback Values with JSON Contact Fields Sample:

Dear %%first_name**Valued Customer%%!

Dear Valued Customer!
{
    "email": "frank@example.com",
    "first_name": ""
}

Fallback text replaces empty or not present values. For example, a contact may have an empty first name, so the fallback text is shown instead.

The format for wildcard fallbacks is %%wildcard_key**fallback text%%. Wildcard key characters are required to be lowercase, alphanumeric or underscores. Fallback text can be plain text.

It is recommended for fallbacks to be used only for short text. For more advanced requirements Conditional Wildcards should be used.

Conditional Wildcards

Conditional Wildcards with JSON Contact Fields Sample:

%%ticket_purchased:CONTAINS:vip%%
    <p>You are a VIP member.</p>
%%ticket_purchased:ELSE%%
    <p>Welcome to the event.</p>
%%ticket_purchased:END%%

%%customer_type:INCLUDES:business:OR:purchases:GREATERTHAN:3%%
    <p>We have the best promotion for you.</p>
%%customer_type:ELSEIF:purchases:GREATERTHAN:1%%
    <p>We have a promotion for you.</p>
%%customer_type:ELSE%%
    <p>Here are a selection of products you may like.</p>
%%customer_type:END%%
{
    "email": "ron@example.com",
    "ticket_purchased": "vip",
    "customer_type": "single",
    "purchases": 3
}

To make it easier to send templates with personalised content we provide conditional wildcards. Conditional wildcards allow for basic programmatic conditionals to be written within content. The wildcards that are available are based on recipient wildcards, attachments and existing contact fields.

Conditional wildcards, allow you to personalise content of an email based on certain data in a list field (or conditions) for a contact. Conditional wildcards allow for basic programmatic conditionals to be written within content. The wildcards that are available are based on recipient wildcards, attachments and existing contact fields.

Values that accept conditional wildcards are:

For more information on using conditional wildcards visit Advanced Conditional Wildcards.

Filters

Search by Contact Field:

GET /v1/lists/432/contacts?email=vincent@example.com

Search for Contacts with Multiple Conditions:

GET /v1/lists/432/contacts?source:ne=promo&city:in=brisbane,sydney

Resource payloads can be modified to return a filtered list of instances by providing query filters.

All values must match the field's type. i.e, you cannot supply a date value to an integer field.

Operator Description
= Return results that match the value.
Example: /v1/lists?name=Black%20Friday
:ne Return results that do not match the value.
Example: /v1/lists/45/contacts?promotion:ne=christmas
:in Return results that match the values in an array.
Example: /v1/messages?id:in=106,107

Ranges

Paginate Contacts by a Number Field:

GET /v1/lists/174/contacts?external_user_id:in=12000..&limit=100

Search Contacts that are Older than a Date:

GET /v1/lists/2974/contacts?creation_date:in=..2020-03-24T04:47:58Z

We allow resources to be filtered by values ranges with the combination of :in and .. operators. Values types are limited to integer, date and datetime.

Resource payloads are limited by the limit parameter.

Operator Range Description
:in=[start]..[end] Between Return results between the [start] and [end] values.
Example: /v1/messages?id:in=1..6
:in=[start].. Greater Than Return results that are greater than the [start] value.
Example: /v1/list/45/contacts?amount:in=50..
:in=..[end] Less Than Return results that are less than the [end] value.
Example: /v1/list/45/contacts?id:in=..10
:in=[start]..[end],
[start]..[end]`
Multiple Ranges Return results between multiple comma separated ranges.
Example: /v1/messages?id:in=1..6,100..120

Pagination

Using pagination you can avoid returning a large number of results by limiting them to a specific number.

Limits

Endpoint with Limits:

GET /v1/messages?limit=10

You can use the limit parameter to limit the number of results. By default, the limit is set to 100 but can be updated to return a maximum of 1,000 results.

This will limit the returned results to 10.

Offsetting

Endpoint with Limit and Offset:

GET /v1/messages?limit=10&offset=30

The offset parameter is used to paginate resources.

The example provided will offset the collection by 30, therefore returning the 31st to 40th collection objects.

Ordering

Collections are ordered by creation_time (descending) instance values by default. Additional order parameters are not supported.

API Discoverability

The goal of the API is to be extremely flexible and self discoverable. Every resource has a _links property detailing the location of that resource, parents or other instances. You can use these links to navigate through the API without knowledge of specific endpoints.

Expansions

Response with expanded children:

{
  "id": 3178,
  "name": "Customer List",
  "creation_time": "2020-04-05T23:46:02Z",
  "last_modified_time": "2020-04-05T23:46:02Z",
  "contacts": null,
  "_links": {
    "self": {
      "href": "/v1/lists/3178?expand=contacts"
    },
    "contacts": {
      "href": "/v1/lists/3178/contacts"
    }
  },
  "_embedded": {
    "contacts": {
      "offset": 0,
      "limit": 100,
      "size": 1,
      "_links": {
        "self": {
          "href": "/v1/lists/3178/contacts"
        }
      },
      "_embedded": {
        "contacts": [
          {
            "id": 347,
            "list_id": 3178,
            "creation_time": "2020-04-05T23:46:02Z",
            "last_modified_time": "2020-04-05T23:46:02Z",
            "email": "john@example.com",
            "mobile": "0400000000",
            "subscribed": {
              "email": true,
              "mobile": true
            },
            "blocked": {
              "email": false,
              "mobile": false
            },
            "account_key": "hUIUyiu879",
            "reply_to": "support@example.com",
            "_links": {
              "self": {
                "href": "/v1/lists/3178/contacts/347"
              },
              "list": {
                "href": "/v1/lists/3178"
              }
            }
          }
        ]
      }
    }
  }
}

To allow for linked resources to be returned in responses we support expansions. By expanding responses more data can be returned and fewer API requests are required.

Expansion can be done via the expand query string parameter.

Rate Limiting

The API limits are:

We suggest that requests are to be sent from a single IP address, per account, at any time.

When sending a high number of requests we recommend monitoring concurrent requests to ensure that limits are not exceeded.

Lists

A list is a collection of contacts.

Lists can be created via the JSON-RPC API or via the platform.

The List Object

Example List

{
    "id": 3178,
    "name": "Customer List",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/lists/3178"
        },
        "contacts": {
            "href": "/v1/lists/3178/contacts"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the instance.
Example: 3178
name string, nullable The instance's name.
Example: Customer List
creation_time string, datetime The instance's creation time.
Example: 2020-04-05T23:46:02Z
last_modified_time string, datetime The instance's last modified time.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object and contacts are provided.

Get all Lists

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/lists"
        }
    },
    "_embedded": {
        "lists": [
            {
                "id": 3178,
                "name": "Customer List",
                "creation_time": "2020-04-05T23:46:02Z",
                "last_modified_time": "2020-04-05T23:46:02Z",
                "_links": {
                    "self": {
                        "href": "/v1/lists/3178"
                    },
                    "contacts": {
                        "href": "/v1/lists/3178/contacts"
                    }
                }
            }
        ]
    }
}

Returns a collection of your lists.

Endpoint

GET /v1/lists{?id,name,creation_time,last_modified_time,fields}

Required Scopes: list.view

Parameters

Field Description
id integer, optional Filter IDs by number filters.
Example: 7
name string, optional Filter names by string filters.
Example: Customer List
creation_time string, datetime, optional Filter creation times by datetime filters.
Example: 2019-12-20T04:12:00Z
last_modified_time string, datetime, optional Filter last modified times by datetime filters.
Example: 2019-12-20T04:12:00Z
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • name
  • creation_time
  • last_modified_time
Example: id,email

Get a List

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "id": 3178,
    "name": "Customer List",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/lists/3178"
        },
        "contacts": {
            "href": "/v1/lists/3178/contacts"
        }
    }
}

Returns the list with the given ID.

Endpoint

GET /v1/lists/{id}{?expand,fields}

Required Scopes: list.view

Parameters

Field Description
id integer, required Unique identifier for the instance.
Example: 89
expand string, optional Expand the response via one or more links. Multiple values can be grouped by commas. Values include:
  • contacts - Emit a collection of contacts linked to the list.
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • name
  • creation_time
  • last_modified_time
Example: id,email

Contacts

A contact is an individual in one of your lists.

Contacts can be created via POST /v1/transactional-sends (with a unique recipient), JSON-RPC API or via the platform.

List Fields

Example Contact with Additional Fields

{
    "id": 347,
    "list_id": 3178,
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "email": "john@example.com",
    "mobile": "0400000000",
    "subscribed": {
        "email": true,
        "mobile": true
    },
    "blocked": {
        "email": false,
        "mobile": false
    },
    "account_key": "hUIUyiu879",
    "reply_to": "support@example.com",
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts/347"
        }
    }
}

Contact instances often contain additional fields, based on their list fields. These fields will be added to each instance automatically.

Field names will be converted to wildcard accepted keys with lowercase, alphanumeric and underscore characters. e.g, the name Reply-To will be converted to the key reply_to.

List fields can be searched using filters, however be sure to convert the field names to keys. e.g, Filter Account Key via the query ?account_key=hUIUyiu879.

For more information on list fields, visit our support article.

The Contact Object

Example Contact

{
    "id": 347,
    "list_id": 3178,
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "email": "john@example.com",
    "mobile": "0400000000",
    "subscribed": {
        "email": true,
        "mobile": true
    },
    "blocked": {
        "email": false,
        "mobile": false
    },
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts/347"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the instance.
Example: 347
list_id integer The list id of the list which the contact is in.
Example: 3178
creation_time string, datetime The instance's creation time.
Example: 2020-04-05T23:46:02Z
last_modified_time string, datetime The instance's last modified time.
Example: 2020-04-05T23:46:02Z
email string, nullable The email of the contact.
Example: john@example.com
mobile string, nullable The mobile phone number of the contact.
Example: 0400000000
subscribed object The subscribed status of the contact.
subscribed.email boolean True if the contact's email is subscribed.
Example: true
subscribed.mobile boolean True is the contact's mobile phone number is subscribed.
Example: true
blocked object The blocked status of the contact.
blocked.email boolean True if the contact's email is blocked.
Example: false
blocked.mobile boolean True if the contact's mobile phone number is blocked.
Example: false
_links object Self discoverable links to the current object are provided.

Get all Contacts

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 347,
                "list_id": 3178,
                "creation_time": "2020-04-05T23:46:02Z",
                "last_modified_time": "2020-04-05T23:46:02Z",
                "email": "john@example.com",
                "mobile": "0400000000",
                "subscribed": {
                    "email": true,
                    "mobile": true
                },
                "blocked": {
                    "email": false,
                    "mobile": false
                },
                "_links": {
                    "self": {
                        "href": "/v1/lists/3178/contacts/347"
                    },
                    "list": {
                        "href": "/v1/lists/3178"
                    }
                }
            }
        ]
    }
}

Returns a collection of your contacts within a linked list.

Endpoint

GET /v1/lists/{list_id}/contacts{?id,email,mobile,creation_time,last_modified_time,fields}

Required Scopes: contact.view

Parameters

Field Description
list_id integer, required Unique identifier for the linked list.
Example: 3178
id integer, optional Filter IDs by number filters.
Example: 347
email string, optional Filter email addresses by string filters.
Example: dan@example.com
mobile string, optional Filter mobile numbers by string filters.
Example: 0400000000
creation_time string, datetime, optional Filter creation times by datetime filters.
Example: 2019-12-20T04:12:00Z
last_modified_time string, datetime, optional Filter last modified times by datetime filters.
Example: 2019-12-20T04:12:00Z
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • list_id
  • creation_time
  • last_modified_time
  • email
  • mobile
  • subscribed
  • blocked
  • creation_time
  • last_modified_time
Example: id,email

Get a Contact

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "id": 347,
    "list_id": 3178,
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "email": "john@example.com",
    "mobile": "0400000000",
    "subscribed": {
        "email": true,
        "mobile": true
    },
    "blocked": {
        "email": false,
        "mobile": false
    },
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts/347"
        }
    }
}

Returns the contact with the given ID within a linked list.

Endpoint

GET /v1/lists/{list_id}/contacts/{id}{?fields}

Required Scopes: contact.view

Parameters

Field Description
list_id integer, required Unique identifier for the linked list.
Example: 3178
id integer, required Unique identifier for the instance.
Example: 347
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • list_id
  • creation_time
  • last_modified_time
  • email
  • mobile
  • subscribed
  • blocked
  • creation_time
  • last_modified_time
Example: id,email

Messages

A message is the metadata for an email or SMS template. Contacts can be sent messages.

The contents of messages are stored within a linked message content instance. These include the HTML/plain text for email message types and text for SMS message types. Message content can be customised with the use of wildcards and conditional wildcards.

Messages can be created via the JSON-RPC API or via the platform.

The Message Object

Example Message

{
    "id": 4847,
    "name": "Reset Password",
    "type": "email",
    "subject": "You requested to reset your password",
    "from_name": "Company Name",
    "from_address": "company@example.com",
    "reply_to": "company@example.com",
    "thumbnail_url": "",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/messages/3847"
        },
        "content": {
            "href": "/v1/messages/3847/content"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the instance.
Example: 4847
name string The name of the message.
Example: Reset Password
type enum, fixed The type of message. Values include email and sms.
Example: email
subject string, nullable The subject of the message.
Example: You requested to reset your password
from_name string, nullable The from name of the sender.
Example: Company Name
from_address string, nullable The from address of the sender.
Example: company@example.com
reply_to string, nullable The reply-to address of the sender.
Example: company@example.com
thumbnail_url string, nullable The URL of the thumbnail generated for the message.
creation_time string, datetime The instance's creation time.
Example: 2020-04-05T23:46:02Z
last_modified_time string, datetime The instance's last modified time.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object and message content are provided.

The Message Content Object

{
    "message_id": 4847,
    "body_html": "<html><body>Email</body></html>",
    "body_text": "Email",
    "_links": {
        "self": {
            "href": "/v1/messages/3847/content"
        },
        "message": {
            "href": "/v1/messages/3847"
        }
    }
}

Attributes

Field Description
message_id integer Unique identifier for the instance.
Example: 4847
body_html string, nullable The HTML body of the message (email message type only).
Example: <html><body>Email</body></html>
body_text string, nullable The text body of the message (Both sms and email message types).
Example: Email
_links object Self discoverable links to the current object and message are provided.

Get all Messages

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/messages"
        }
    },
    "_embedded": {
        "messages": [
            {
                "id": 4847,
                "name": "Reset Password",
                "type": "email",
                "subject": "You requested to reset your password",
                "from_name": "Company Name",
                "from_address": "company@example.com",
                "reply_to": "company@example.com",
                "thumbnail_url": "",
                "creation_time": "2020-04-05T23:46:02Z",
                "last_modified_time": "2020-04-05T23:46:02Z",
                "_links": {
                    "self": {
                        "href": "/v1/messages/3847"
                    },
                    "content": {
                        "href": "/v1/messages/3847/content"
                    }
                }
            }
        ]
    }
}

Returns a collection of your messages.

Endpoint

GET /v1/messages{?id,type,name,subject,from_name,from_address,reply_to,thumbnail_url,creation_time,last_modified_time,fields}

Required Scopes: message.view

Parameters

Field Description
id integer, optional Filter IDs by number filters.
Example: 754
type string, optional Filter by message type. Values include:
  • email - Email message
  • sms - SMS/Text message
Example: email
name string, optional Filter names by string filters.
Example: One Time Password
subject string, optional Filter subject by string filters.
Example: Reset Your Password
from_name string, optional Filter sender from name by string filters.
Example: Support Team
from_address string, optional Filter sender from address by string filters. These can be an email address for email types or a phone number for sms types.
Example: marketing@example.com
reply_to string, optional Filter sender reply-to address by string filters. These can be an email address for email types. sms types do not utilise this field.
Example: support@example.com
thumbnail_url string, optional Filter thumbnail url by string filters.
creation_time string, datetime, optional Filter creation times by datetime filters.
Example: 2019-12-20T04:12:00Z
last_modified_time string, datetime, optional Filter last modified times by datetime filters.
Example: 2019-12-20T04:12:00Z
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • type
  • name
  • subject
  • from_name
  • from_address
  • reply_to
  • thumbnail_url
  • creation_time
  • last_modified_time
Example: id,from_address

Get a Message

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "id": 4847,
    "name": "Reset Password",
    "type": "email",
    "subject": "You requested to reset your password",
    "from_name": "Company Name",
    "from_address": "company@example.com",
    "reply_to": "company@example.com",
    "thumbnail_url": "",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/messages/3847"
        },
        "content": {
            "href": "/v1/messages/3847/content"
        }
    }
}

Returns the message with the given ID.

Endpoint

GET /v1/messages/{id}{?expand,fields}

Required Scopes: message.view

Parameters

Field Description
id integer, required Unique identifier for the instance.
Example: 294
expand string, optional Expand the response via one or more links. Multiple values can be grouped by commas. Values include:
  • content - Emit the message content instance linked to the message.
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • type
  • name
  • subject
  • from_name
  • from_address
  • reply_to
  • thumbnail_url
  • creation_time
  • last_modified_time
Example: id,from_address

Get a Message's Content instance

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "message_id": 4847,
    "body_html": "<html><body>Email</body></html>",
    "body_text": "Email",
    "_links": {
        "self": {
            "href": "/v1/messages/3847/content"
        },
        "message": {
            "href": "/v1/messages/3847"
        }
    }
}

Returns the message content with the given message ID.

Endpoint

GET /v1/messages/{message_id}/content{?expand,fields}

Required Scopes: message.view

Parameters

Field Description
message_id integer, required Unique identifier for the linked message.
Example: 294
expand string, optional Expand the response via one or more links. Multiple values can be grouped by commas. Values include:
  • message - Emit the message instance linked to the message content.
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • message_id
  • body_html
  • body_text
Example: id,body_html

Transactional Sends

Transactional sends allow for templates to be sent to contacts. It is recommended to send transactional templates in the following scenarios:

Email Templates - Raw HTML/Text

Transactional Send with Raw HTML/Text

{
    "list_id": 345,
    "type": "email",
    "group_name": "Reset Password",
    "from_name": "Company Name",
    "from_address": "support@example.com",
    "subject": "How to Reset your Password",
    "body_html": "<html><body>Hi %%name%%<br>Click <a src='%%reset_link%%'>here</a> to reset your password</body></html>",
    "body_text": "Hi %%name%%, visit %%reset_link%% to reset your password",
    "recipients": [
        {
            "email": "sam@example.com",
            "name": "Sam",
            "reset_link": "https://example.com/reset-password?key=KJHuIyhUIOh"
        }
    ]
}

To send with your own content you need to supply one or both body_html and body_text content for the email within the request.

Email Templates - Messages

Transactional Send with a Message ID

{
    "list_id": 345,
    "type": "email",
    "group_name": "Happy Birthday",
    "message_id": 427,
    "recipients": [
        {
            "email": "john@example.com"
        },
        {
            "email": "philip@example.com"
        }
    ],
    "attachments": [
        {
            "type": "application/pdf",
            "name": "event-tickets.pdf",
            "content": "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"
        }
    ]
}

To utilise an existing message you can supply a message_id within the request. All email types (including Drag and Drop) can be sent.

Messages and message content can be discovered via the messages endpoints.

When sending a message template the following fields are automatically collected from the message and used as defaults. That said, if these parameters are provided within the request payload they will override the message defaults.

SMS/Text Templates

Within the current API version only email messages and template types can be sent via transactional sends.

Transactional Group Names and IDs

We group results for transactional sends into transactional groups. Transactional groups can be discovered via the transactional groups endpoints.

A transactional group can be linked by supplying a group_id or group_name.

Recipient Contacts

Recipients are the details that link the transactional send to contacts.

Email Recipient Examples

{
    "contact_id": 2147
}
{
    "email": "bob@example.com"
}
{
    "email": "sam@example.com",
    "location": "Brisbane, Australia",
    "tickets": 3
}

SMS Recipient Examples

{
    "contact_id": 2147
}
{
    "mobile": "0400000000"
}
{
    "mobile": "0400000000",
    "location": "Brisbane, Australia",
    "tickets": 3
}

Contact Unique Identifiers

Each recipient supplied must provide exactly one identifying field. These fields are (grouped by message type):

By default the contact_id field will be checked first and fail if it does not exist in the list provided.

New Contacts

Successfully validated recipients with a unique identifier that does not exist in the supplied list (via list_id) are created as new contacts. Recipients with an invalid contact_id will not be sent to and will be marked as failed. Existing contacts are not updated.

Wildcards and Conditional Wildcards

Email Examples

{
    "list_id": 345,
    "type": "email",
    "group_name": "Happy Birthday",
    "message_id": 427,
    "recipients": [
        {
            "email": "john@example.com",
            "first_name": "John",
            "url_key": "oiserjoifdewh"
        }
    ]
}

Fields that are within recipient payloads can also be used as wildcards within the body_html, body_text and subject.

The following keys are excluded from wildcards:

For more information on using wildcards and conditional wildcards, visit the wildcards introduction.

Attachments

Email Examples

{
    "list_id": 345,
    "type": "email",
    "group_name": "Happy Birthday",
    "message_id": 427,
    "recipients": [
        {
            "email": "john@example.com"
        }
    ],
    "attachments": [
        {
            "type": "application/pdf",
            "name": "event-tickets.pdf",
            "content": "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"
        }
    ]
}
{
    "list_id": 345,
    "type": "email",
    "group_name": "Happy Birthday",
    "message_id": 427,
    "recipients": [
        {
            "email": "john@example.com",
            "attachments": [
                {
                    "type": "application/pdf",
                    "name": "event-tickets.pdf",
                    "content": "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"
                }
            ]
        }
    ]
}

Attachments can be applied to all and/or individual recipients. If attachments are provided to both the request root and within an individual recipient, then both sets will be available within the template for the recipient. It is required that all attachments use unique names.

The content for attachments is a base64 encoding of the file submitted.

Inline Attachments

Example Inline Attachment

{
    "list_id": 217,
    "type": "email",
    "group_name": "Register Today",
    "from_name": "Company Name",
    "from_address": "support@example.com",
    "subject": "Register Today",
    "body_html": "<html><body>Hi %%name%%,<br/>Register with your QR code:<br/><img src='%%attachment:qr-code.png%%' alt=''/></body></html>",
    "recipients": [
        {
            "email": "ben@example.com",
            "name": "Ben",
            "attachments": [
                {
                    "type": "image/png",
                    "name": "qr-code.png",
                    "content": "iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAEeElEQVR4Xu2c0XIqMQxDu///0XRaliGFZvcodkxodV+vSRzJkp0wdLtcLpcP/1sGgc2ELMPFdyImZC0+TMhifJgQE7IaAovl4x5iQhZDYLF0rBATshgCi6VjhZiQxRBYLB1ZIdu2pR+hfU5T1+89xbXrkOc6dV8CAtn3cR0TsiNiQprSsELuYIQUMiLJ29aqpbTS7lUzyae3bySfXm4kn1TLGtnQhBx3Hyvklx7yqkIb+j6ESL5XA71eoU5KJAcVVLJm1rmONJKmEDKlmJDzYdmEnFjWjEJ7W4WokxUBr12TKJasSdY518Y1YmmFmBBA46uaH7l7kGq2QsCNnExEBGx1HWI16r7RC+bbW1av4ntiJwpXn3IIscB8/kYPMSHN8zuxCLVSybsQqfIsomhlZzwJpU5ZMxInwBN7IYUT9X4TsiNgQgq/MSTNMqIiQqaqfNUqH9cPTVmRZCP3gdlEzTgXXdOE7EiR+wYF9RZHeldYIWpSajy5kZMnlah1qHlnxcsKydqYjMMEVFLZI5U6+5zd86/2CyorRCwfApgao35jSC6PRIFkOFCVEr3PyJalgq1OUyrYKgDqmGxCGgQI2CSGkKyuoyqQEisrhC58iyMHnRHTy5PYFBkUyPoqVl/xJmRHLevWLrbkJ85MyLsTQppi5P5ALIVcDEnFR2Iik+GRlckKMSFXOE1I50+yzBjDZ4/qqQohdkGmC9UuyJpkFFXtlOSZOXHJlmVCeGmMTFwm5Bd81T75UoWQS5yqItIgidUQyyJ7jVS2chFO7SEm5NiyVHweV5MtS92QPEOQqrVCOoUQGTNngEoIJ22YFEUkhuTwFRNSCJnXsxpeVqNV8yGOQGJMCEVgj4tU/5KEVKpFxPpDVVfkMhix5VTLMiHPZTIyPqf1EBOyACHEd0kTjXiw+ll1SiT2pX5lUH4xJKNo1iFMCPh9iAm5aqC8h0TkrPYcsheZcEixqDZL9qWTYaipE5AqYwgwJqT5pk9tqKqK/iUhVHqjcWoFq8NBZAhQ1T6CgWxZI5sonzEhI6OAgrAYa0JEQlTACB/qBVO1qTYH8q41Y32Cw7S3LLr5Lc6E3BGTe4gVclxu6tDwuFqIENHtfuxNEifkE3sh43YPZpInsUTqGibkBCkT0gBkhQBdkSlFfQuK2E7kNg+O+yMkYtF0rzTLmlHN5GZsQjrP7yaEauBkSlN/p15pWVmPhcRq1Obdm6xIzkeULG1Z5HCqMrPGWxMi/mCHkJl1f4jcc6ZdDNVKJRZB7JHYUUQV5FxkqqQdZjnLIlVLyCQAkHVMSOdiSO4qhARCOOkPZK8R9aYphCRIwCAVSQ4a8XXy2aw8p/UQE/KMACkcE9KZ1ohNRV4OaMGGLItuchYX6Q/qJEbsKGsqK1fIGdD0/03IHSkrZMeCVLM6JpM1wz2EVr3jxhCQFTK2jT9FETAhFKmiOBNSBDTdxoRQpIriTEgR0HQbE0KRKoozIUVA021MCEWqKM6EFAFNtzEhFKmiOBNSBDTdxoRQpIriPgGzSEo+SG5vWQAAAABJRU5ErkJggg=="
                }
            ]
        }
    ]
}

Attachments can be added to the body HTML as inline Content-ID identifiers. To add an inline attachment you can add a wildcard in the format of %%attachment:[attachment.name]%%. The output will be similar to cid:content_[generated ID].

Generally inline attachments are used as Content-ID identifiers within images. e.g, <img src="%%attachment:[attachment.name]%%" alt="" />.

We recommend that only the following types are used as image attachments:

In templates, it is recommended that you assign a unique name to each inline attachment.

Accepted File Types

The following file types are accepted as attachments:

Account Owner Confirmation

Before a transactional send can be completed the account owner's email address must be confirmed. You can re-send the confirmation email by having the account owner log into the dashboard and click the 'Re-send confirmation' link. If no link is found then the email address is already confirmed.

Domain Configuration

For email sends it is recommended that the domains used within the from_address and bcc_address fields are configured within the platform. A configured domain will require SPF and DKIM domain records to be added, supplied within the Account > Domains page in the platform.

You can find out more about how to configure your domain name at Emails Going to Spam? Set up Your Domain Records. Please note that certain domains may not send emails until they are configured.

Once a domain is configured within the platform then it will also be DMARC aligned, and eligible for a DMARC policy.

Automations

The "API Upload" automations campaign event is triggered for each contact that is successfully added or updated. The endpoint does not trigger subscription autoresponders or send subscription notification messages.

Asynchronous Transactional Sends

All transactional sends are sent asynchronously. What does this mean for requests?

Request Limits and Validation

Each transactional send request has the following limits and validation criteria:

Transactional Send

Send a template (via a message or raw HTML/text) to a list of recipients. The send reports will be stored within transactional groups.

HTTP Response

202 Accepted
content-type: application/json; charset=UTF-8

Endpoint

POST /v1/transactional-sends

Required Scopes: send.email and/or send.sms

Attributes

Field Description
list_id integer, required Unique identifier for the linked list.
Example: 89
group_id integer, optional Unique identifier for the linked group.
Example: 248
group_name string, optional Unique name for the linked group.
Example: Password Reset Report
message_id integer, optional Unique identifier for the linked message. Providing a message_id will override any type provided.
Example: 754
type enum, required The message send type. Values include:
  • email
  • sms

Example: email
subject string, optional The message subject line.
Example: Password Reset
from_name string, optional The sender from name.
Example: Vision 6 Support
from_address string, optional The sender from address.
Example: support@example.com
reply_to string, optional The sender reply-to address for email message types.
Example: support@example.com
bcc_address string, optional The sender bind carbon copy (bcc) address for email message types.
Example: support@example.com
body_html string, optional The HTML body of the email message type.
Example: Hi %%name%%<br>Click <a src="%%reset_link%%">here</a> to reset your password
body_text string, optional The text body of the email and sms message types.
Example: Hi %%name%%, visit %%reset_link%% to reset your password
include_unsubscribed boolean, optional By default all unsubscribed email addresses for the recipients supplied will not be sent to. To ignore this behaviour set this to true.
Example: false
recipients array, required Collection of recipients. A maximum of 100 recipients can be sent per request.
recipients.*.id string, optional Unique identifier for the contact.
Example: 135478
recipients.*.email string, optional The email of the contact.
Example: frank@example.com
recipients.*.mobile string, optional The mobile phone number of the contact.
Example: 0400000000
attachments array, optional Collection of attachments.
attachments.*.type string, required The mimetype of the attachment.
Example: text/calendar
attachments.*.name string, required The name of the attachment.
Example: this_meeting_could_have_been_an_email.ical
attachments.*.content string, required Base64 encoded attachment data.
Example: QkVHSU46VkNBTEVOREFSCkNBTFNDQUxFOkdSRUdPUklBTgpCRUdJTjpWRVZFTlQKU1VNTUFSWTpBYnJhaGFtIExpbmNvbG4KRFRTVEFSVDoyMDA4MDIxMgpEVEVORDoyMDA4MDIxMwpEVFNUQU1QOjIwMTUwNDIxVDE0MTQwMwpFTkQ6VkVWRU5UCkVORDpWQ0FMRU5EQVI=

Transactional Groups

The results for transactional sends are added to transactional groups.

The Transactional Group Object

Example Transactional Group

{
    "id": 135478,
    "name": "Reset Password Messages",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_sent_time": "2020-04-05T23:46:02Z",
    "sent": 72,
    "failed_contacts": 2,
    "bounced": 0,
    "delivered": 70,
    "opened": 15,
    "clicked": 14,
    "unsubscribed": 0,
    "_links": {
        "self": {
            "href": "/v1/transactional-groups/135478"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the instance.
Example: 135478
name string The name of the group. All group names are unique.
Example: Reset Password Messages
creation_time string, datetime The instance's creation time.
Example: 2020-04-05T23:46:02Z
last_sent_time string, datetime The instance's last sent time. This is the last time that a send was added to the group.
Example: 2020-04-05T23:46:02Z
sent integer Total recipients, i.e. total contact count that has been specified in all sends for this transactional group.
Example: 72
failed_contacts integer Total number of recipients that failed the validation.
Example: 2
bounced integer Total number of recipients that had an email bounce.
Example: 0
delivered integer Total number of recipients who successfully received a message.
Example: 70
opened integer One open is recorded for each individual recipient who opens a message, without duplicate opens.
Example: 15
clicked integer Total number of recipients that clicked any link (one or more links), one or more times.
Example: 14
unsubscribed integer Total number of recipients that unsubscribed because of a message from this transactional group (may happen multiple times per contact).
Example: 0
_links object Self discoverable links to the current object are provided.

Get all Transactional Groups

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/transactional-groups"
        }
    },
    "_embedded": {
        "transactional-groups": [
            {
                "id": 135478,
                "name": "Reset Password Messages",
                "creation_time": "2020-04-05T23:46:02Z",
                "last_sent_time": "2020-04-05T23:46:02Z",
                "sent": 72,
                "failed_contacts": 2,
                "bounced": 0,
                "delivered": 70,
                "opened": 15,
                "clicked": 14,
                "unsubscribed": 0,
                "_links": {
                    "self": {
                        "href": "/v1/transactional-groups/135478"
                    }
                }
            }
        ]
    }
}

Returns a collection of your transactional groups.

Endpoint

GET /v1/transactional-groups{?id,name,creation_time,last_sent_time,sent,failed_contacts,bounced,delivered,opened,clicked,unsubscribed,fields}

Required Scopes: report.view

Parameters

Field Description
id integer, optional Unique identifier for the instance.
Example: 54
name string, optional Filter names by string filters.
Example: One Time Password
creation_time string, datetime, optional Filter creation times by datetime filters.
Example: 2019-12-20T04:12:00Z
last_sent_time string, datetime, optional Filter last sent times by datetime filters.
Example: 2019-12-20T04:12:00Z
sent integer, optional Filter the total sent messages by number filters.
Example: One Time Password
failed_contacts integer, optional Filter the total failed contact messages by number filters.
Example: One Time Password
bounced integer, optional Filter the total bounced messages by number filters.
Example: One Time Password
delivered integer, optional Filter the total delivered messages by number filters.
Example: One Time Password
opened integer, optional Filter the total opened messages by number filters.
Example: One Time Password
clicked integer, optional Filter the total clicked messages by number filters.
Example: One Time Password
unsubscribed integer, optional Filter the total unsubscribed messages by number filters.
Example: One Time Password
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • name
  • creation_time
  • last_sent_time
  • sent
  • failed_contacts
  • bounced
  • delivered
  • opened
  • clicked
  • unsubscribed
Example: id,sent

Get a Transactional Group

HTTP Response

200 OK
content-type: application/json; charset=UTF-8
{
    "id": 135478,
    "name": "Reset Password Messages",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_sent_time": "2020-04-05T23:46:02Z",
    "sent": 72,
    "failed_contacts": 2,
    "bounced": 0,
    "delivered": 70,
    "opened": 15,
    "clicked": 14,
    "unsubscribed": 0,
    "_links": {
        "self": {
            "href": "/v1/transactional-groups/135478"
        }
    }
}

Returns the transactional group with the given ID.

Endpoint

GET /v1/transactional-groups/{id}{?fields}

Required Scopes: report.view

Parameters

Field Description
id integer, optional Unique identifier for the instance.
Example: 54
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • name
  • creation_time
  • last_sent_time
  • sent
  • failed_contacts
  • bounced
  • delivered
  • opened
  • clicked
  • unsubscribed
Example: id,sent

Errors

Conventional HTTP response codes are used to indicate the success or failure of an API request. HTTP response codes in the 2xx range indicate success, while codes in the 4xx range indicate an error.

400 Bad Request

HTTP Response

400 Bad Request
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 400,
    "message": "The server did not understand the request.",
    "developer_message": "Check that the request body is properly encoded and not empty.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#400-bad-request"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: The server did not understand the request.
developer_message string A message to assist developers with correcting the request payload.
Example: Check that the request body is properly encoded and not empty.
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#400-bad-request

401 Unauthorized

HTTP Response

401 Unauthorized
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 401,
    "message": "Authentication is required for the request.",
    "developer_message": "Authentication is required but the Authorization header was missing from the request.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#401-unauthorized"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: Authentication is required for the request.
developer_message string A message to assist developers with correcting the request payload.
Example: Authentication is required but the Authorization header was missing from the request
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#401-unauthorized

403 Forbidden

HTTP Response

403 Forbidden
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 403,
    "message": "You do not have permission to access the resource.",
    "developer_message": "Check to make sure you have permission to perform the requested operation.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#403-forbidden"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: You do not have permission to access the resource.
developer_message string A message to assist developers with correcting the request payload.
Example: Check to make sure you have permission to perform the requested operation.
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#403-forbidden

404 Not Found

HTTP Response

404 Not Found
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 404,
    "message": "Could not find the requested resource.",
    "developer_message": "Check the requested URI to make sure it corresponds to a valid resource.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#404-not-found"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: Could not find the requested resource.
developer_message string A message to assist developers with correcting the request payload.
Example: Check the requested URI to make sure it corresponds to a valid resource.
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#404-not-found

405 Method Not Allowed

HTTP Response

405 Method Not Allowed
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 405,
    "message": "The operation is not permitted.",
    "developer_message": "The operation is not permitted.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#405-method-not-allowed"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: The operation is not permitted.
developer_message string A message to assist developers with correcting the request payload.
Example: The operation is not permitted.
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#405-method-not-allowed

409 Conflict

HTTP Response

409 Conflict
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 409,
    "message": "There was an issue with the request.",
    "developer_message": "Check the fields object for more information and correct any issues before re-submitting the request.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#409-conflict"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: There was an issue with the request.
developer_message string A message to assist developers with correcting the request payload.
Example: Check the fields object for more information and correct any issues before re-submitting the request.
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#409-conflict

422 Unprocessable Entity

HTTP Response

422 Unprocessable Entity
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 422,
    "message": "There was an error in the request.",
    "developer_message": "Check all the fields supplied in the request are valid.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#422-unprocessable-entity"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: There was an error in the request.
developer_message string A message to assist developers with correcting the request payload.
Example: Check all the fields supplied in the request are valid.
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#422-unprocessable-entity

429 Too Many Requests

HTTP Response

429 Too Many Requests
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 429,
    "message": "Too many requests. API rate limit exceeded.",
    "developer_message": "Too many requests. API rate limit exceeded.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#429-too-many-requests"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: Too many requests. API rate limit exceeded.
developer_message string A message to assist developers with correcting the request payload.
Example: Too many requests. API rate limit exceeded.
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#429-too-many-requests

503 Unavailable

HTTP Response

503 Unavailable
content-type: application/json; charset=UTF-8
{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "code": 503,
    "message": "The service you requested is not available at this time.",
    "developer_message": "The service may be busy or down for maintenance. Please retry the request in a few moments.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "[current_url]"
        },
        "error": {
            "href": "/rest-api/#503-unavailable"
        }       
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
code integer The HTTP response code.
Example: 400
message string A user friendly error message.
Example: The service you requested is not available at this time.
developer_message string A message to assist developers with correcting the request payload.
Example: The service may be busy or down for maintenance. Please retry the request in a few moments.
timestamp string The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#503-unavailable

Changelog

1.0.0