v1

latestOpenAPI 3.1.02026-07-2466150275.0 KB

Form Instances

Aggregate Form Instance Signatures

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.

post/v1/form-instance/signature/aggregate

Request body

querystring nullable

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.

skipinteger nullable

Number of records to skip before returning records

limitinteger nullable

Number of records to return

sort_direction'asc' | 'desc'

Direction to sort the sort_column - ascending or descending.

date_startstring 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_offstring 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_columnstring nullable

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

group_bystring[] required

Column names to group by

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_archivedboolean nullable

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

project_is_archivedboolean 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_idinteger nullable

Filter to signatures on submissions of a specific form template.

form_type_idinteger nullable

Filter to signatures on submissions of a specific form type.

site_idinteger nullable

Filter to signatures on submissions at a specific site.

user_idinteger nullable

Filter to signatures by a specific user.

signature_type'signature' | 'approve' | 'disapprove' | 'associated'

Supported signature types for SQL GROUP BY queries.

Example request

{
  "aggregations": [
    {
      "alias": "total_signatures",
      "column": "id",
      "operator": "count"
    },
    {
      "alias": "unique_signers",
      "column": "user_id",
      "operator": "count_distinct"
    }
  ],
  "date_filter_column": "updated_at",
  "group_by": [
    "type",
    "is_reviewer"
  ],
  "is_archived": false,
  "limit": 50,
  "project_is_archived": false,
  "skip": 0,
  "sort_column": "unique_signers",
  "sort_direction": "desc"
}

Response

Successful Response

errorboolean

A boolean error indicator.

messagestring nullable

Optional message.

Example response

{
  "data": {
    "data": [
      {
        "is_reviewer": false,
        "total_signatures": 520,
        "type": "worker",
        "unique_signers": 85
      },
      {
        "is_reviewer": true,
        "total_signatures": 180,
        "type": "supervisor",
        "unique_signers": 12
      },
      {
        "is_reviewer": true,
        "total_signatures": 95,
        "type": "manager",
        "unique_signers": 5
      }
    ],
    "metadata": {
      "aggregations": [
        {
          "alias": "total_signatures",
          "column": "id",
          "operator": "count"
        },
        {
          "alias": "unique_signers",
          "column": "user_id",
          "operator": "count_distinct"
        }
      ],
      "group_by_columns": [
        "type",
        "is_reviewer"
      ]
    },
    "total_groups": 3
  }
}