Custom pivots API

The custom pivots API allows you to take existing list and pivot reports and represent them as JSON. This enables developers to pull related data from multiple types of records in a single API query.

There are two types of reports that you can pull via this API: list or pivot. See the documentation below for a full explanation of their formats.

The :report_id parameter is the ID of a saved view in Aha! To find the ID of an existing report, choose the report from the Views -> Saved views dropdown in Aha! Then take the large number at the end of the URL with the term custom_pivots in it. For example, /bookmarks/custom_pivots/6434552458299516367 has a :report_id of 6434552458299516367.

Get the pivot view of a saved report

GET /api/v1/bookmarks/custom_pivots/:report_id

The pivot view is similar to the list view, but is more referential. There are six attributes in the JSON response: top_level_columns, columns, top_level_rows, rows, cells, field_definitions.

The columns attribute is an object where the keys are the unique id of column within the report. Rows and field_definitions have the same referential treatment. The attributes are the id in order to ease lookup.

Since pivot reports are referential in nature and can be nested, there are top_level_rows and top_level_columns. This allows you to easily iterate throught the nested structure. Each column and row object contain a reference to their parent object (parent_ref). They also contain a set of references to their direct children (child_refs). They also, along with cells, contain a reference to their field definition (via field_definitions_refs).

The field definitions object is an object that acts as a map to look up the definitions of the fields used within the report. Similarly to the list view, these contain table, field, and title attributes.

The cells attribute is a set of nested arrays. The lowest level array is a list of the fields for a specific value. Each element in this set has a row_ref, column_ref, and field_definition_ref which can be used to lookup which column and row this value is representing. Just like the list view, there are multiple formats of the value:

• id: The unique id of the object
• plain_value: A string representation of the object
• html_value: An HTML representation of the object. This is the same HTML that is used in Aha! to represent the value in our reports.
• rich_value: If the object is a reference to another object (such as a tag), the, this will be the object representation.

There is no pagination with pivot report.

Example request

GET /api/v1/bookmarks/custom_pivots/801750833?view=pivot

Example CURL command

curl -g "https://company.aha.io/api/v1/bookmarks/custom_pivots/801750833?view=pivot" -X GET \
	-H "Authorization: Bearer 15b60d42d4bc417284a246ced6877b0bf13fb4aca415f7b55f7006bc3694a8ab" \
	-H "Content-Type: application/json" \
	-H "Accept: application/json"

Request

authorization: Bearer 15b60d42d4bc417284a246ced6877b0bf13fb4aca415f7b55f7006bc3694a8ab
contentType: application/json
accept: application/json

Response

Status: 200 OK
contentType: application/json; charset=utf-8

Response body