Aggregate Form Instances

post

https://developer.beta.salussafety.io/v1/form-instance/aggregate

Aggregate form instances with GROUP BY operations.

Allows grouping by status, form_id, type_id, site_id, and other fields with
aggregation functions like COUNT, SUM, AVG, MIN, MAX. Uses the same base filters
and company scoping as the search endpoint for consistent behavior.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request model for form instance aggregation queries.

query

string | null

Keywords should be space separated and are ANDed together, so all keywords must be present but they can be present in any of the fields specified above.

skip

integer | null

Defaults to 0

Number of records to skip before returning records

limit

integer | null

Defaults to 50

Number of records to return

sort_direction

string

enum

Defaults to desc

Direction to sort the sort_column - ascending or descending

Allowed:

date_start

date-time | null

If sorting on updated_at or created_at, and date_cut_off is provided, return only records that were created or updated (whichever is being sorted on) between date_start and date_cut_off

date_cut_off

date-time | null

If sorting on updated_at or created_at, return only records that were created or updated (whichever is being sorted on) between the initial value (determined by sort order) and the cutoff date.

For example, sorting on created_at ascending with a date_cut_off will return all records from the oldest creation date to the cutoff date. By comparison, sorting on created_at descending with a date_cut_off will return all records from the most recent creation date to the cutoff date.

sort_column

string | null

Column to sort aggregation results by (must be in group_by or an aggregation alias)

group_by

array of strings

required

Column names to group by

Group By*

aggregations

array of objects

required

Aggregation functions to apply

Aggregations*

date_filter_column

string

enum

Defaults to updated_at

Column to apply date_start/date_cut_off filters on. One of 'created_at', 'updated_at', or 'submitted_on' (excludes drafts since they have no submitted_on).

Allowed:

is_archived

boolean | null

Defaults to false

Filter by entity archived status. Defaults to False (only active entities). Use True for archived only, None to include all.

project_is_archived

boolean | null

Defaults to false

Filter by parent project's archived status. Defaults to False (only active projects). Use True for archived projects only, None to include all.

query_mode

string

enum

Defaults to own

'own' aggregates your company's submissions; 'shared' aggregates subcontractor submissions shared with your company.

Allowed:

form_instance_status

string

enum

Filter by form instance status before aggregating. Use None to include all statuses.

Allowed:

form_id

integer | null

Filter to submissions of a specific form template.

site_id

integer | null

Filter to submissions at a specific site.

type_id

integer | null

Filter to submissions of a specific form type.

submitted_by_user_id

integer | null

Filter to submissions by a specific user.

asset_id

integer | null

Filter to submissions for a specific asset.

Responses

200Successful Response

400Invalid aggregation request

403Permission denied

409Integrity Error or Data Conflict

422Validation Error