---
title: "Aggregate Form Instance Signatures"
method: POST
path: "/v1/form-instance/signature/aggregate"
tags: ["Form Instances"]
---

# Aggregate Form Instance Signatures

`POST /v1/form-instance/signature/aggregate`

Aggregate form instance signatures with GROUP BY operations.

Allows grouping by type, is_reviewer, form_submit_id, and user_id with
aggregation functions like COUNT, COUNT_DISTINCT, MIN, MAX.

## Request body

- SignatureAggregationModel — Request model for form signature aggregation queries. Supports cross-entity group-by dimensions (site_id, form_id, type_id) from the parent FormSubmit, in addition to direct FormSubmitUser columns.
  - `query` string, nullable — Keywords should be space separated and are `AND`ed together, so all keywords must be present but they can be present in any of the fields specified above.
  - `skip` integer, nullable — Number of records to skip before returning records
  - `limit` integer, nullable — Number of records to return
  - `sort_direction` 'asc' | 'desc' — Direction to sort the `sort_column` - ascending or descending.
  - `date_start` string, date-time, nullable — 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` string, date-time, nullable — 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, nullable — Column to sort aggregation results by (must be in group_by or an aggregation alias)
  - `group_by` string[], required — Column names to group by
  - `aggregations` AggregationFieldLiteralIdUserIdFormSubmitIdSiteIdFormId[], required — Aggregation functions to apply
    - `column` 'id' | 'user_id' | 'form_submit_id' | 'site_id' | 'form_id', required — Column name to aggregate
    - `operator` 'sum' | 'avg' | 'count' | 'min' | 'max' | 'count_distinct', required — Supported aggregation operators for SQL GROUP BY queries.
    - `alias` string, nullable — Optional alias for the result column
  - `date_filter_column` 'created_at' | 'updated_at' | 'submitted_on' — Column to apply date_start/date_cut_off filters on. One of 'created_at', 'updated_at' (both on FormSubmitUser), or 'submitted_on' (parent FormSubmit; excludes signatures on drafts).
  - `is_archived` boolean, nullable — Filter by entity archived status. Defaults to False (only active entities). Use True for archived only, None to include all.
  - `project_is_archived` boolean, nullable — Filter by parent project's archived status. Defaults to False (only active projects). Use True for archived projects only, None to include all.
  - `form_id` integer, nullable — Filter to signatures on submissions of a specific form template.
  - `form_type_id` integer, nullable — Filter to signatures on submissions of a specific form type.
  - `site_id` integer, nullable — Filter to signatures on submissions at a specific site.
  - `user_id` integer, nullable — Filter to signatures by a specific user.
  - `signature_type` 'signature' | 'approve' | 'disapprove' | 'associated' — Supported signature types for SQL GROUP BY queries.

## Response `200`

Successful Response

- ApiGenericResponseSignatureAggregationResponse
  - `error` boolean — A boolean error indicator.
  - `message` string, nullable — Optional message.
  - `data` SignatureAggregationResponse — Response model for signature aggregation queries.
    - `data` object[], required — List of aggregation result rows. Each row contains the group_by column values and computed aggregation values. Keys are the group_by column names and aggregation aliases (or default names like 'count_id' if no alias provided).
    - `total_groups` integer, required — Total number of distinct groups returned by the aggregation query
    - `metadata` AggregationMetadataLiteralTypeIsReviewerFormSubmitIdUserIdSiteIdFormIdTypeIdCreatedDateCreatedWeekCreatedMonthCreatedYearUpdatedDateUpdatedWeekUpdatedMonthUpdatedYearSubmittedDateSubmittedWeekSubmittedMonthSubmittedYearLiteralIdUserIdFormSubmitIdSiteIdFormId, required
      - `group_by_columns` string[], required — List of column names used for grouping the results
      - `aggregations` AggregationFieldLiteralIdUserIdFormSubmitIdSiteIdFormId[], required — List of aggregation functions that were applied to produce the results
        - `column` 'id' | 'user_id' | 'form_submit_id' | 'site_id' | 'form_id', required — Column name to aggregate
        - `operator` 'sum' | 'avg' | 'count' | 'min' | 'max' | 'count_distinct', required — Supported aggregation operators for SQL GROUP BY queries.
        - `alias` string, nullable — Optional alias for the result column
      - `time_series` TimeSeriesMetadata — Metadata for time-series aggregation results.
        - `time_field` string, required — The time-based column used for grouping (e.g., 'created_month')
        - `granularity` 'date' | 'week' | 'month' | 'year', required — The time granularity of the grouping
        - `category_fields` string[] — Non-time columns used for grouping (e.g., ['status'])

## Other responses

- `400` — Invalid aggregation request
- `403` — Permission denied
- `409` — Integrity Error or Data Conflict
- `422` — Validation Error

---

[API](https://skmtc.dev/salussafety/apis/salus-developer-api.md) · [All operations](https://skmtc.dev/salussafety/apis/salus-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/salussafety/salus-developer-api/revisions/ef065f44da25/schema)