Forms

Forms (also called registers) are the structured templates your organisation uses to capture information — incident reports, vehicle checks, consent records, and more. On this page you'll find the form and form submission models, the endpoint for listing templates, and the endpoint for listing a template's submissions. Reading forms requires the read:register scope.

Submission metadata is returned — who submitted, the state, when, and which version — but the submitted field values are never exposed on the public API, as they can contain sensitive participant information.

The form model

Forms are versioned: the id is a stable string reference for the template, while the name tracks its latest version. Every form object carries an object discriminator and a livemode flag, and nullable scalars are always present (as null) rather than omitted.

Properties

Name
object
Type
string
Description
The string "form". A discriminator describing the object's type.
Name
id
Type
string
Description
Stable string reference (the template's ref). Use this as the {id} when listing submissions and as starting_after when paginating.
Name
name
Type
string | null
Description
The template's name, taken from its latest version. null if the latest version has no name.
Name
category
Type
string | null
Description
The category the template is filed under, or null if uncategorised.
Name
status
Type
string
Description
Either active or archived.
Name
submissionCount
Type
integer
Description
The number of completed submissions across all versions of the template. In-progress drafts are excluded, so this count is typically lower than the number of items returned by the submissions endpoint (which includes drafts).
Name
livemode
Type
boolean
Description
true when the object was returned by a live key (ds_live_…), false in test mode.

The form submission model

A form submission is a single completed or in-progress filling of a template. Only metadata is exposed — never the submitted field values.

Properties

Name
object
Type
string
Description
The string "form_submission". A discriminator describing the object's type.
Name
ref
Type
string
Description
Stable string reference for the submission. Use this as starting_after when paginating.
Name
staff
Type
object
Description
The staff member who made the submission, as { id, name }.
Name
draft
Type
boolean
Description
true if the submission is still an in-progress draft, false once completed.
Name
processed
Type
boolean
Description
Whether the submission has been processed.
Name
submittedAt
Type
string
Description
When the submission was created, as an ISO 8601 UTC timestamp (e.g. 2026-06-01T22:14:05Z).
Name
version
Type
object
Description
The template version the submission was made against, as { name, identifier }. identifier is null when the version has none.
Name
livemode
Type
boolean
Description
true when the object was returned by a live key (ds_live_…), false in test mode.

GET/v1/forms

List forms

Returns a list of form templates, ordered by name. Requires the read:register scope. The response is the uniform list envelope: object is "list", url is /v1/forms, has_more indicates whether further pages exist, and data holds the form objects.

Optional attributes

Name
active
Type
boolean
Description
Filter by status — true for active templates, false for archived. Omit to return both.
Name
limit
Type
integer
Description
The number of items to return (1–100). Defaults to 25.
Name
starting_after
Type
string
Description
A pagination cursor — the id of the last form you saw. The response returns forms ordered after this one.

Request

GET

/v1/forms

curl -G https://api.diversitysync.com/v1/forms \
  -H "Authorization: Bearer {access_token}" \
  -d active=true \
  -d limit=25

Response

{
  "object": "list",
  "url": "/v1/forms",
  "has_more": true,
  "data": [
    {
      "object": "form",
      "id": "7d3f9a21-4c8b-4e1a-9f2c-1b6e5d0a8c44",
      "name": "Incident Report",
      "category": "Compliance",
      "status": "active",
      "submissionCount": 192,
      "livemode": true
    }
  ]
}

GET/v1/forms/{id}/submissions

List form submissions

Returns a list of submissions for the template identified by {id} (the form's id/ref), ordered by submission time (most recent first). Requires the read:register scope. Returns a 404 resource_missing error if no template with that id exists in your organisation. Field values are never included — only the submission metadata documented above.

Optional attributes

Name
processed
Type
boolean
Description
Filter by processed state — true for processed submissions only, false for unprocessed.
Name
from
Type
string
Description
Only include submissions created at or after this ISO 8601 datetime (UTC).
Name
to
Type
string
Description
Only include submissions created before this ISO 8601 datetime (UTC).
Name
limit
Type
integer
Description
The number of items to return (1–100). Defaults to 25.
Name
starting_after
Type
string
Description
A pagination cursor — the ref of the last submission you saw. The response returns submissions ordered after this one.

Request

GET

/v1/forms/{id}/submissions

curl -G https://api.diversitysync.com/v1/forms/7d3f9a21-4c8b-4e1a-9f2c-1b6e5d0a8c44/submissions \
  -H "Authorization: Bearer {access_token}" \
  -d processed=true \
  -d limit=25

Response

{
  "object": "list",
  "url": "/v1/forms/7d3f9a21-4c8b-4e1a-9f2c-1b6e5d0a8c44/submissions",
  "has_more": true,
  "data": [
    {
      "object": "form_submission",
      "ref": "fsub_8e1d4c7b9a20",
      "staff": { "id": 482, "name": "Jordan Avery" },
      "draft": false,
      "processed": true,
      "submittedAt": "2026-06-01T22:14:05Z",
      "version": {
        "name": "Incident Report",
        "identifier": "INC-v3"
      },
      "livemode": true
    }
  ]
}