Skip to main content
Planview Customer Success Center

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.

           

Click to expand or shrink

           

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.

           

Click to expand or shrink

           

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

           

TIP

Check out detailed documentation on Advanced Reporting API endpoints here