Get a form submission
Workforce module
GET/form-submissions/{id}formSubmissions.get
A submitted form: answers against one template version, score, GPS stamp, signature and approval. Returns one form submission with its `ETag`. A form submission the caller may not see returns 404.
- Requires the capability knowledge.sop.read.
- OAuth scopes: knowledge.
- Error statuses: 400, 401, 404, 429. Errors are RFC 9457 problem details.
Path and query parameters
| Field | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Identifier of the form submission. |
| 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_]*)*$ |
Response 200: 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 |
{
"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."
}Code samples
curl -X GET "$XOS_BASE_URL/form-submissions/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" \
-H "Authorization: Bearer $XOS_API_KEY"const { data, etag } = await xos.formSubmissions.get("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f");response = xos.form_submissions.get("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f")xos form-submissions get 0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f