Advanced Reporting API: Getting Started
The Reporting API (Application Programming Interface) is designed to be a REST interface, with resource-based URLs that accept and return JSON. Resources that return reporting data also support comma-separated values (CSV) and tab-separated values (TAB/TSV). All API calls must be made over HTTPS.
Step 1: Get a Token
Each of the reporting data API endpoints require an authentication token. To request a token, you will POST your AgilePlace account credentials to the /io/reporting/auth endpoint.
Step 2: Send a Request Using a Token
Once an authentication token is created, it can be used as a URL query string parameter (e.g. ?token=xxyyzz) or as a Bearer Token HTTP header.
Response formats
Each of the API endpoints that return reporting data support CSV, TAB and JSON responses. By default, CSV will be returned. Requesting a specific format can be done using the format query string parameter, or as an extension. For more information, see Export Parameters.
Errors
The Reporting API uses standard HTTP response codes to indicate the success or failure a request. HTTP response codes in the 200-2xx range indicate success. Response codes in the 400-4xx range indicate a failed request, such as bad or missing parameters. Authentication tokens expire after a predefined number of minutes. Requesting an endpoint with an expired token will return an HTTP status code 401. Response codes in the 500-5xx range indicate a failure with AgilePlace's servers to fulfill the request.
Request failures also return a JSON response that provides additional information to explain the reason for the failure.
Examples
Invalid credentials
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Login failed: email or password is incorrect"
}
Expired authentication token
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid token"
}