List form submission rows
Workforce module
GET/form-submissionsformSubmissions.list
A submitted form: answers against one template version, score, GPS stamp, signature and approval. Returns a cursor page of form submission rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.
- Requires the capability knowledge.sop.read.
- OAuth scopes: knowledge.
- Cursor-paginated: limit, cursor, fields, sort and filter apply.
- Error statuses: 400, 401, 429. Errors are RFC 9457 problem details.
Path and query parameters
| Field | Type | Required | Description |
|---|---|---|---|
| limit | Limit | No | Page size. Default 50, maximum 200.Constraints: range 1 to 200 |
| cursor | Cursor | No | Opaque cursor from `next_cursor` of the previous page.Constraints: length 1 to any |
| fields | Fields | No | Sparse fieldset: a comma-separated list of top-level fields to return. `id` is always returned.Constraints: pattern ^[a-z_][a-z0-9_]*(,[a-z_][a-z0-9_]*)*$ |
| sort | Sort | No | Sort keys, comma-separated; a leading `-` sorts descending. Without `sort`, the documented default order applies (coded lists sort in numeric code order).Constraints: pattern ^-?[a-z_][a-z0-9_]*(,-?[a-z_][a-z0-9_]*)*$ |
| filter | Filter | No | Filter grammar `filter[field][op]=value`. Operators: eq, ne, lt, lte, gt, gte, in (comma-separated values), is_null (true or false) and contains. Conditions combine with AND. |
Response 200: a page of FormSubmission
| Field | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Identifier of the form submission. |
| org_id | string (uuid) | Yes | Identifier of the owning organization, derived from the parent row and never accepted from the caller. |
| created_at | string (date-time) | Yes | When the row was created. |
| created_by | string (uuid) | null | Yes | Person who created the row; null for seed, platform or system writes. |
| updated_at | string (date-time) | Yes | When the row was last updated. |
| updated_by | string (uuid) | null | Yes | Person who last updated the row; null for seed, platform or system writes. |
| form_template_id | string (uuid) | Yes | Identifier of the form answered. |
| form_template_version_id | string (uuid) | Yes | Identifier of the version answered. |
| project_id | string (uuid) | null | Yes | Identifier of the project the submission belongs to. |
| record_id | string (uuid) | null | Yes | Identifier of the record the project submission became. |
| submitted_by_membership_id | string (uuid) | Yes | Identifier of the member who submitted. |
| answers | object | Yes | Answers keyed by field key. |
| score | number | null | Yes | Points earned. |
| max_score | number | null | Yes | Points available on the shown fields. |
| passed | boolean | null | Yes | Whether the pass score was met. |
| latitude | number | null | Yes | WGS 84 latitude.Constraints: range -90 to 90 |
| longitude | number | null | Yes | WGS 84 longitude.Constraints: range -180 to 180 |
| accuracy_m | number | null | No | GPS accuracy in metres.Constraints: range 0 to any |
| signer_name | string | null | Yes | Name of the signer.Constraints: length 1 to 200 |
| signature_path | string | null | Yes | Signature image path in the field-media bucket.Constraints: length 1 to 500 |
| signed_at | string (date-time) | null | Yes | When it was signed. |
| submission_state | "Submitted" | "Approved" | "Rejected" | "Recorded" | Yes | Submission state. |
| decided_by_membership_id | string (uuid) | null | Yes | Identifier of the approver who decided. |
| decision_note | string | null | Yes | Approver's note.Constraints: length 1 to 1000 |
{
"data": [
{
"id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"created_at": "2026-10-08T14:30:00Z",
"created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"updated_at": "2026-10-08T14:30:00Z",
"updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"form_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"form_template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"submitted_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"answers": {
"hoist_ok": true
},
"score": 3,
"max_score": 3,
"passed": true,
"latitude": 25.7617,
"longitude": -80.1918,
"accuracy_m": 8,
"signer_name": "Frank Adeyemi",
"signature_path": "org/forms/sig.png",
"signed_at": "2026-10-08T14:30:00Z",
"submission_state": "Submitted",
"decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"decision_note": "Good to lift."
}
],
"next_cursor": null
}Code samples
curl -X GET "$XOS_BASE_URL/form-submissions" \
-H "Authorization: Bearer $XOS_API_KEY"for await (const row of xos.formSubmissions.listAll()) {
console.log(row);
}for row in xos.form_submissions.list_all():
print(row)xos form-submissions list --all