REST is a standardised technology that uses JSON to pass structured requests and responses and the HTTP protocol to invoke and select methods.

When providing input you must ensure that the request is well-formed, paying attention to make sure that the JSON request definition adheres to the required case sensitivity which can be different depending on the method or operation you are calling. Please make sure to check, where provided, the sample request and response for each method or operation that you are going to call.

Dates and times

When you are using date/time values in your operation or method calls, you must be aware that our API runs on UTC (Coordinated Universal Time) and returns all dates/times in UTC in ISO 8601 format. To make sure that you are using the correct time you can use the Get server time operation to get the current time of the server our API runs on. This ensures that any time-dependent routines run at the expected time.

Paging through data

🚧

The pagination mechanism differs between our v2 and v3 services. You must ensure you use the correct method for the call in use. Learn how to identify which API version a call uses here.

Where API calls have paging support the following paging mechanisms are used:

For v2 service calls

Each call to the API method can return usually up to 1000 records but for some select calls this can be higher, the number of records to fetch is specified by the Select parameter.

To iterate through the record set you use the Select and Skip parameters in tandem. The Skip parameter allows you to specify an offset into the record set. If you want to iterate through the record set by 100 records at at time you should set the Select parameter to 100 and the Skip parameter to 0, which returns records 1 to 100. For subsequent calls you should increment the Skip parameter by your Select parameter value (100) and continue to call until 0 records are returned as this indicates the end of the record set.

For v3 service calls

We use the Seek Pagination (also referred to as Continuation Token or Cursor technique) for pagination with v3 service calls. This technique is simple to use as you only have to state a maximum number of data items to return per call, and optionally set a marker to indicate where the result set should start from.

Passing the pagination parameters

The parameters to control the pagination should be passed on the query string of the URI:

For the initial call to a service that supports pagination you would normally not pass any of the pagination parameters, as you are starting a new data set, and this call will return a set of pagination links which you can then subsequently use to move through the data set.

Pagination Links

Pagination links are helpful URI links and markers to retrieve related data pages when returning a page of data, such as the next page link, previous page link etc… These links can be used to navigate the data set, for API calls use the marker value to move through the data set when passed in the marker query string.

Pagination links are returned by service calls that support pagination as follows:

links object:

linkDetails object:

Example
In this example the limit is set to 2 and this is the returned response from the first page:
URI: https://api.dotdigital.com/accounts/v1?limit=2&~marketSector=eq::retail

{
  "_links": {
    "self": {
      "link": "https://api.dotdigital.com/accounts/v1/accountId/12456",
      "marker": "12456"
    },
    "first": {
      "link": "https://api.dotdigital.com/accounts/v1/accountId/12456",
      "marker": "12456"
    },
    "next": {
      "link": "https://api.dotdigital.com/accounts/v1/accountId/12456",
      "marker": "12458"
    }
  },
  "_items": [
    {
      "id": "12456",
      "name": "Acme corp.",
      "created": "2020-01-01T15:43:10Z",
      "updated": "2020-01-15T13:05:00Z",
      "marketSector": "retail",
      "users": "https://api.dotdigital.com/users/v1?12456"
    },
    {
      "id": "12457",
      "name": "Smith inc",
      "created": "2019-06-01T15:43:10Z",
      "updated": "2019-09-15T13:05:00Z",
      "marketSector": "retail",
      "users": "https://api.dotdigital.com/users/v1?12457"
    }
  ]
}