Engage API

A unified API for the Questline Engage platform

View Endpoints

Overview

The Engage API is organized around REST and is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. The API uses built-in HTTP features — such as headers, methods, and status codes — which can be understood by any off-the-shelf HTTP client. The Engage API only supports requests and responses in JSON format.

Security

Every request to the Engage API requires an API key, which must be Base64-encoded and sent as part of the Authorization HTTP header.

For example, if your API key is 7a9aa97e-3fed-46b6-b39a-fe0f7ef268e7, the Base64-encoded value of that is N2E5YWE5N2UtM2ZlZC00NmI2LWIzOWEtZmUwZjdlZjI2OGU3. On each request to the Engage API, the client must add the Authorization HTTP header, as such:

Authorization: Basic N2E5YWE5N2UtM2ZlZC00NmI2LWIzOWEtZmUwZjdlZjI2OGU3

Any request made to the Engage API without a valid API key will result in a 401 Unauthorized response.

HTTP Methods

The Engage API uses standard HTTP methods as actions for all API requests, and most URIs accept multiple HTTP methods (one per request). The table below is a general rule of thumb for which HTTP methods are used and when.

Method Description
GET Retrieves a single object or a list of objects.
POST Creates an object or a relationship between objects.
PUT Updates an object.
DELETE Deletes an object.

HTTP Status Codes

The Engage API uses standard HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate a server error.

Code Description Method Usage
200 OK The request was successful. GET, POST, PUT, DELETE success
201 Created The item sent in the request was successfully created. POST success
400 Bad Request The request was bad. Any
401 Unauthorized API key was invalid or not supplied. Any
403 Forbidden The client is not allowed to perform the request. Any
404 Not Found The requested item doesn't exist. GET failure
500 Internal Server Error Something went wrong processing the request. GET, POST, PUT, DELETE failure

Errors

In addition to HTTP status codes, responses from the Engage API contain additional error information about their request. Every response contains an Error object that signals whether or not an error occurred. If no error occurred during the request, the Error object will be null. In cases where an error does occur during a request, the Error will contain two properties: ErrorId and ErrorMessage, where ErrorId is a reference number and ErrorMessage is a human-readable message providing more details about the error.

Below is an example of what the Error object looks like:

}
    "Error": {
        "ErrorId": 123456,
        "ErrorMessage": "An error occurred."
    }
}

Expands

The Engage API supports the concept of expands, which allows a client to retrieve related data for a given item during the same request, and made possible with the expand parameter. For example, a client can retrieve a subscriber (id = c16eac10-f846-4885-a9b4-088272ea2e9d) and its attributes by using the following endpoint:

GET https://api.questline.com/subscribers/c16eac10-f846-4885-a9b4-088272ea2e9d?expand=attributes

A client can request multiple expands by concatenating them together, separated by a comma. For example, to retrieve the same subscriber, but with its attributes and subscriptions, a client would use the following endpoint:

GET https://api.questline.com/subscribers/c16eac10-f846-4885-a9b4-088272ea2e9d?expand=attributes,subscriptions

If an endpoint supports expands, there will be an Expands section as part of its help page; otherwise, no Expands section will be shown.

Filters

The Engage API also supports filters, which behave similar to SQL where clauses that limit the results for a request. The filter parameter consists of tuples, with each item in the tuple separated by the tilde (~) character. The filter tuple takes the following format:

key~operator~value

Below is the list of supported filter operators:

Name Operator Example Applies To
Contains cn filter=address~cn~questline Strings
EndsWith ew filter=address~ew~@questline.com Strings
Equal eq filter=address~eq~info@questline.com Any type
GreaterThan gt filter=created~gt~2015-09-01 Any type
GreaterThanOrEqual ge filter=created~ge~2015-09-01 Any type
LessThan lt filter=created~lt~2015-09-01 Any type
LessThanOrEqual le filter=created~le~2015-09-01 Any type
NotEqual ne filter=isactive~ne~true Any type
StartsWith sw filter=address~sw~info@ Strings

For example, to retrieve all subscribers that have been created since Sept 1, 2015, a client will use the following endpoint:

GET https://api.questline.com/subscribers?filter=created~ge~2015-09-01

A client can also use multiple filter tuples, separated by a comma, to limit results even further. For example, to retrieve all subscribers with a questline.com email address, created since Sept 1, 2015, a client will use the following endpoint:

GET https://api.questline.com/subscribers?filter=created~ge~2015-09-01,address~ew~@questline.com

The Engage API filters can also query for nullable items by using a "null" value for the eq (equal) and ne (not equal) operators, as such:

GET https://api.questline.com/subscribers?filter=address~eq~null
GET https://api.questline.com/subscribers?filter=address~ne~null

If an endpoint supports filters, there will be a Filters section as part of its help page; otherwise, no Filters section will be shown.

Sorting

When retrieving lists of items, the Engage API supports using the sort parameter to sort the results. For example, to retrieve all subscribers in descending order by created date, a client will use the following endpoint:

GET https://api.questline.com/subscribers?sort=created~desc

The sort parameter consists of key-value pairs, separated by the tilde (~) character. This allows a client to use multiple sorts on a set of results, with each key-value pair separated by a comma. For example, to retrieve all subscribers sorted by email address in ascending order and then by created date in descending order, a client will use the following endpoint:

GET https://api.questline.com/subscribers?sort=address~asc,created~desc

If an endpoint supports sorting, there will be a Sorting section as part of its help page; otherwise, no Sorting section will be shown.

Paging

In many cases, retrieving lists of items needs to be done a page at a time, which the Engage API handles by providing the page parameter. For example, to retrieve page 4 of a list of subscribers with a page size of 25, a client will use the following endpoint:

GET https://api.questline.com/subscribers?page=index~3,size~25

The page parameter consists of two key-value pairs: index and size. Both key-value pairs are separated by the tilde (~) character and should always be used together, separated by a comma. Note that the index key-value pair is 0-based.

For endpoints that support paging, the following properties will be returned in the response:

Property Description
NextPageUrl The URL of the next page of data; will be blank if there are no more pages.
PageIndex The current page index that was requested.
PageSize The current page size that was requested.
TotalPages The total number of pages for the request.
TotalResults The total number of results for the request.

Below is an example of what these properties look like as part of a response:

{
    "NextPageUrl": "https://api.questline.com/subscribers?page=index~4,size~25",
    "PageIndex": 3,
    "PageSize": 25,
    "TotalPages": 5,
    "TotalResults": 108
}

If no page size is specified, the default size of 25 will be used.

The maximum page size supported is 1000. If requests are made with page sizes higher than 1000, then only 1000 results will be returned.

If an endpoint supports paging, there will be a Paging section as part of its help page; otherwise, no Paging section will be shown.

Dates and Timestamps

All date and timestamp values retrieved through the Engage API reflect UTC time, and are comprised of the following format:

yyyy-MM-ddTHH:mm:ss

Format Description
yyyy The year as a four-digit number.
MM The month, from 01 through 12.
dd The day of the month, from 01 through 31.
T The separator of date and time.
HH The hour, using a 24-hour clock from 00 to 23.
mm The minute, from 00 through 59.
ss The second, from 00 through 59.

Filtering with Dates and Timestamps

When using filters with date values, a client can specify a time as part of the date value, using the above format. For example, to retrieve all subscribers that were created on Dec 1, 2015 between 9:00am and 5:00pm EST (non daylight savings time), a client will use the following endpoint:

GET https://api.questline.com/subscribers?filter=created~ge~2015-12-01T14:00:00,created~le~2015-12-01T22:00:00