Outcome
Read the authorized form response records, with exact answer fields, protection and collection limits.
GET /api/forms/{formId}/submissions
Before you start
Use the intended original organization and discover a canonical Forms workspace through supported Auth resources. Bind it separately as workspace resource context. Resolve the formId through authorized forms.list/references; an input id is not a grant.
A user bearer resolves the requested workspace against actual grants; reads require read access, export creation requires read_write. API keys retain the exact Auth-verified workspace binding. Concrete application permission is workspace:read for the two reads and workspace:write for export creation.
These guides contain source-derived synthetic UNRUN examples only. No real answers, respondent identities, exports, delivery actions, notifications, models, keys or provider operations were read or executed. Public technical guidance does not publish application data.
Request
Action: app_topolo_forms.submissions.list. Validate the published input and bind the discovered workspace separately. This is a read-only action.
Behavior and response
Returns HTTP200 {submissions:[...]} with id,formId,answers,respondentName,respondentEmail,submittedAt,placementContext. Selected source reads every matching row ordered by submitted_at DESC; no LIMIT, cursor, total, date filter or stable tie-breaker is implemented. Do not add unsupported limit/cursor inputs.
Each selected submission is unprotected for answers/respondent name/email/placement context before mapping. answers_json parses to an object with {} fallback if parsing fails; absent placement context maps to null. Returned answer keys are stored answers, not filtered to the current form fields, revalidated, redacted, deduplicated or re-evaluated for UI visibility.
The list is a private-data read even if all respondent identifiers are null. A returned row is not independent evidence that the respondent was unique, email verified, consent valid or a downstream action delivered. No delivery retry/export/notification is triggered by this handler.
Scope and consistency
Original organization, verified workspace and discovered form scope the concrete read before producing these responses. Missing/out-of-scope form returns HTTP404 {error:not_found}; the response does not reveal another tenant.
Form reads and response/export/delivery queries are separate operations without a shared transaction or snapshot isolation. Protection or database failure is not an empty collection; retain actual request/status evidence instead of changing context, keys or environment policy.
Catalog structural output overlays permit generic carriers. The precise envelopes and fields described here come from the pinned handler and mapper, not that broad schema alone. Current sourceRevision matches the reviewed source; loaded runtime, key health, browser behavior and provider outcomes remain separately unproved.
Worked examples
One readable fictional response
Complete source-derived synthetic UNRUN HTTP200. Exactly one matching readable row; fictional null respondent identity and explicit null placement. No actual response was read.
Input:
{
"formId": "forms_docs_fixture"
}
Response:
{
"submissions": [
{
"id": "formsubmission_docs_fixture",
"formId": "forms_docs_fixture",
"answers": {
"note": "Synthetic response"
},
"respondentName": null,
"respondentEmail": null,
"submittedAt": "2026-10-20T08:00:00.000Z",
"placementContext": null
}
]
}
Verify the real authorized scope and interpret only the documented response. Fictional identifiers and this example authorize no application operation.
Existing form without responses
Complete source-derived synthetic UNRUN HTTP200. Form lookup succeeded and the submission query successfully returned no rows; not a decryption or database failure.
Input:
{
"formId": "forms_docs_fixture"
}
Response:
{
"submissions": []
}
Verify the real authorized scope and interpret only the documented response. Fictional identifiers and this example authorize no application operation.
No matching form
Complete source-derived synthetic UNRUN HTTP404. Successful original authentication/workspace/permission checks, then no matching form row. No cross-tenant probe.
Input:
{
"formId": "forms_absent_docs_fixture"
}
Response:
{
"error": "not_found"
}
Verify the real authorized scope and interpret only the documented response. Fictional identifiers and this example authorize no application operation.
Verify and recover
-
Confirm each actual formId matches the discovered target and retain the request workspace context; submission rows do not include organization/workspace ids.
-
Preserve the exact submission ids only for an authorized follow-up. Do not infer total boundedness or cross-store equality with a form count/summary taken at another time.
-
On actual auth/protection/database failures retain sanitized code/status/request id. Shared-runtime errors may have different carriers; failure is not an empty response or evidence of no committed export.
Read only. Preserve failures and reconcile the original authorized target; never submit responses, retry deliveries or change protection as read recovery.
Refusals
403 / forbidden: Preserve the original context and route denial; obtain legitimate access from the owner, never broaden or substitute credentials.
404 / not_found: Reconcile the discovered form and canonical workspace within the original authorized context.
Related actions
Change log
- 2026-10-21: Added exact current handler/mapper behavior, authorization and collection or mutation limits, complete synthetic response examples, verification and recovery. Source review only; examples remain unrun.