API Conventions

Please note the following conventions when working with the APIs.

The URI structure for GET/PUT/DELETE is v2/[collection]/[item]/[subcollection]/[item].  

  • The [collection]/[subcollection] is always specified in plural form; e.g. “subscribers”, “emails”.  
  • The [item] represents the ID for the individual resource; e.g. subscriber ID or subscription name.
  • Resources should never end in a slash; e.g. /v2/reference-data?view=schema is okay /v2/reference-data/?view=schema produces a 404 error.

Subscriber IDs are case insensitive and the API does not perform validation on email addresses. Lower case conversion should be performed on all emails by the client application before submitting to the Subscribers API.

The URI structure for POST controller methods reflects the item or collection that the controller operates on. For example, v2/[collection]/[controller]

As per REST standards, a PUT operation replaces the entire item or collection it operates on.  Partial updates to the resource, where permitted, are performed by a POST controller method (typically “update”) on the item or collection.

Submitting an empty collection in a PUT operation will erase all data in the collection.

Depending on the nature of the resource, a DELETE operation does not always delete the resource. In some cases, it may archive the resource or change its status to inactive (e.g., unsubscribing a subscriber to a division via DELETE subscribers/{id}/subscriptions/{name}).

A resource URI is treated as case sensitive. For example, GET subscribers/JohnSmith retrieves a different resource than GET subscribers/johnsmith.  However, all query parameters that follow the resource URI are case-insensitive.

For GET operations that potentially retrieve a large result set, the results may be “paged through” by using the limit and offset query parameters.  Limit represents the number of results to be retrieved in the response payload (typically, the maximum is 100 and the default is 25), and offset represents the number of result set items to be skipped before retrieving the first item in the response payload (the default is 0). For example, GET v2/subscribers?limit=100&offset=400 would retrieve the fifth 100-item “page” of results, or, results #401 through #500.

ETags and optional If-Match processing are provided for some resources.  These are described on a separate documentation page.

Authorization/authentication is performed via “Api-User” and “Api-Key” request headers.  These values will be provided to you as part of the API V2 onboarding process.