Engage API

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.

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.

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.

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

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."
    }
}

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.

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.

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.

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 10000. If requests are made with page sizes higher than 10000, then only 10000 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.

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