API Reference
Form Submissions
Poll for patient form submission results via the API
Form Submissions
Retrieve the results of digital forms that patients fill out. These read-only endpoints support a polling pattern: periodically check for new or updated submissions using a timestamp filter.
List submissions
GET /form-submissions
Returns a paginated list of form submissions. Supports standard pagination plus additional filters for polling.
Query parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Zero-based page index (default 0) |
pageSize | integer | Items per page (default 20) |
status | string | Filter by status: Pending, Opened, Completed, Rejected |
updatedFrom | string | ISO 8601 date. Only submissions updated on or after this time |
updatedTo | string | ISO 8601 date. Only submissions updated on or before this time |
patientId | string | Filter by patient UUID |
formId | string | Filter by form UUID |
Response
{
"data": [
{
"id": "submission-uuid",
"submissionStatus": "Completed",
"createdAt": "2025-05-20T08:00:00.000Z",
"updatedAt": "2025-05-20T09:15:00.000Z",
"receivedAt": "2025-05-20T09:15:00.000Z",
"requestedBy": "user-uuid",
"patient": {
"id": "patient-uuid",
"firstName": "Ana",
"lastName": "Horvat",
"mobileNumber": "+385991234567"
},
"form": {
"id": "form-uuid",
"displayName": "Patient Intake Form"
}
}
],
"count": 1
}
The list response does not include the
data field (the patient's actual form answers). Use the detail endpoint below to retrieve it. This keeps polling payloads small, since form answers can contain large base64 signatures.Get submission detail
GET /form-submissions/:id
Returns a single submission including the full data field with the patient's answers.
Response
{
"id": "submission-uuid",
"submissionStatus": "Completed",
"data": {
"field1": "answer1",
"field2": "answer2",
"signature": "data:image/png;base64,..."
},
"createdAt": "2025-05-20T08:00:00.000Z",
"updatedAt": "2025-05-20T09:15:00.000Z",
"receivedAt": "2025-05-20T09:15:00.000Z",
"requestedBy": "user-uuid",
"patient": {
"id": "patient-uuid",
"firstName": "Ana",
"lastName": "Horvat",
"mobileNumber": "+385991234567"
},
"form": {
"id": "form-uuid",
"displayName": "Patient Intake Form"
}
}
Polling pattern
Use the updatedFrom filter to efficiently poll for new and updated submissions.
Initial poll
Fetch all completed submissions:
curl -X GET "https://api.voxares.com/api/v1/integration/form-submissions?status=Completed" \
-H "Authorization: Bearer vox-YOUR-API-KEY"
Record the current timestamp (e.g. 2025-05-20T10:00:00Z).
Subsequent polls
Pass the last poll timestamp as updatedFrom to only get submissions that changed since then:
curl -X GET "https://api.voxares.com/api/v1/integration/form-submissions?status=Completed&updatedFrom=2025-05-20T10:00:00Z" \
-H "Authorization: Bearer vox-YOUR-API-KEY"
For each returned submission, call the detail endpoint to retrieve the full answers:
curl -X GET "https://api.voxares.com/api/v1/integration/form-submissions/submission-uuid" \
-H "Authorization: Bearer vox-YOUR-API-KEY"
We recommend polling every 1-5 minutes depending on your use case. Use
updatedAt (not createdAt) as the polling anchor because submissions move through statuses. A submission created as Pending only becomes Completed later, which updates updatedAt.Submission statuses
| Status | Description |
|---|---|
Pending | Form has been sent to the patient but not yet opened |
Opened | Patient has opened the form link |
Completed | Patient has submitted the form with answers |
Rejected | Submission was rejected or expired |