Getting Started

Accessing the Service

You should have been given an analyticDomain and already have a user account that you intend to use for your client.

Only HTTPS is permitted.

Warning

You must be provided with a client id and secret before continuing. You may do this here: Actual Experience Service Desk

All URIs mentioned in these docs refer to https://<analyticsDomain>/hq<URI> unless otherwise stated (for example, the Notifications WebSocket resides at wss://<analyticsDomain>/notifications/ws).

General Notes

Mandatory and Optional Fields

All fields not specified as optional are mandatory and always present in case of a response field.

Timestamps

All date fields e.g. "2017-01-23T13:24:56Z" are in ISO8601 format. Note that the measurement data is stored with timestamps in UTC time. The start date (SD) and end date (ED) parameters are thus also expected to be in UTC, not in the local timezone.

Pagination

All list requests (GET) support parameters limiting the output:

<URI>?limit=<limit>&skip=<skip>

where "limit" gives the maximum number of entries listed, and "skip" the number of entries from the beginning not included in the list

ETags

Clients should specify the If-None-Match header for any GET and If-Match for PUT requests if it has received an ETag header from a previous response to the same URI. The server will then respond with a newer document if the ETag value supplied in the header does not match the latest version, or will respond with a 304 Not Modified response and empty response body if the value matches.

Response Codes

Successful response codes are 200 for GET and 201 for PUT. An unsuccessful code, 40X means the client must not try the same request again since the request is malformed or is unauthorised. If a 50X code is observed, the client should back-off and try again later. 503 indicates that the system is undergoing maintenance.

The following general custom response codes are used as response to many various requests:

`486`: denied credit; maximum number of analytics used for a partner would be exceeded

`487`: denied target limit; target protection limit for the number of agents monitoring the target would be exceeded

`488`: denied dependents; the object to be deleted is used in design

`489`: denied credit; maximum number of analytics used for an organisation would be exceeded

Unicode

All fields where arbitrary user input are accepted (e.g. agentDescription, partnerName, etc) can accept unicode, and therefore the whole json request and response where these fields exist should be treated as such.

In the case of Digital Users – all requests may be sent in plain ASCII if it suites the environment e.g. Digital User Embedded where memory may be limited. All Digital User API responses may also be assumed to be ASCII only. This is not the case in all other APIs where Unicode must always be supported/assumed.