SAsalussafety
Form Instances

Search Form Instances

Changed on

Search for forms that match the provided search terms.

Keywords are searched for in the title, instance identifier, site identifier, site name, site address, company name, submitted user first and last name, draft name, device name, and device type fields.

get/v1/form-instance/

Request

  • Base URL
    https://developer.beta.salussafety.io
  • URL
    https://developer.beta.salussafety.io/v1/form-instance/
  • Auth
    • HTTP bearer
    • or OAuth 2
      Client credentials
      Token URL: https://guardian.beta.salussafety.io/token
    • or OAuth 2
      Authorization code: https://guardian.beta.salussafety.io/authorize
      Token URL: https://guardian.beta.salussafety.io/token

Query parameters

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.

Example:foo bar
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.

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

Example:2022-03-04
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.

Example:2022-03-23
sort_column'updated_at' | 'created_at' | 'id'

Which column to sort on

Column to sort the results on

query_mode'own' | 'shared'

Specify the search mode for the form instances.

The mode of the search query, it's mutually exclusive, either search for forms submitted by the current company, or search for form that are shared with this company via site submissions where this company is parent company.

external_project_idstring nullable

An optional filter to match by external project ID. This is an exact match.

Example:1321
external_company_idstring nullable

An optional filter to match by external company ID. This is an exact match, additionally, this filter can only be applied when the search mode is for shared form instances; otherwise this parameter is ignored.

Example:5541
external_onlyboolean nullable

If set to true this flag will filter form instances that belong to projects that have a linked external_id attached to the project. This is useful mainly for integration scenarios.

Example:true
project_idinteger nullable

This is the project ID of a SALUS project, in other parts of the system this is also referred to as the site ID.

Example:12
form_instance_statusFormInstanceStatus[] nullable

The statuses of the form instances to filter. Repeat the parameter to match any of several statuses, e.g. ?form_instance_status=completed&form_instance_status=disapproved.

[
  "completed"
]
form_idinteger nullable

The identifier value for a form template to filter by.

Example:15
form_type_idinteger nullable

The numeric identifier related to the form type.

Example:3
submitted_user_idinteger nullable

Filter by the user identifier of the user that has submitted the form.

Example:2
created_by_user_idinteger nullable

Filter by the user identifier of the user that created the form instance.

Example:2
signer_user_idinteger nullable

Filter by the user identifier of a user that has signed the form.

Example:2
is_restrictedboolean nullable

Filter forms instances that have the flag set to restrict access to full access roles.

Example:true
is_archivedboolean nullable

Ensures that forms that have not been archived are returned by default, but allows toggling the filter..

has_corrective_actionboolean nullable

Filter by whether the form instance has associated corrective action feed posts. If true, only return form instances with at least one feed post where action_required is true. If false, only return form instances with no such feed posts.

Example:true
incident_idinteger nullable

Filter by incident ID. Returns form instances linked to this incident via the IncidentForm relationship.

Example:10
has_public_accessboolean nullable

Filter by whether the submission is exposed via a public access link (e.g. shared submission review, signature, collaboration, or full-access URLs). If true, only return submissions referenced by an active PublicAccess record for the current company. If false, only return submissions with no public access link.

Example:true

Response

Successful Response

errorboolean

A boolean error indicator.

messagestring nullable

Optional message.

Changes

  • 9ee72e046aa1Revision changes
    • breaking

      removed the enum value completed from the query request parameter form_instance_status

    • breaking

      removed the enum value disapproved from the query request parameter form_instance_status

    • breaking

      removed the enum value draft from the query request parameter form_instance_status

    • breaking

      removed the enum value draft_pending_review from the query request parameter form_instance_status

    • breaking

      removed the enum value pending_review from the query request parameter form_instance_status

    • info

      for the query request parameter form_instance_status, the type was generalized from string to array