Outcome
Inspect up to200 delivery records without triggering retries or mistaking ledger states for downstream completion.
GET /api/forms/{formId}/deliveries
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.deliveries.list. Validate the published input and bind the discovered workspace separately. This is a read-only action.
Behavior and response
After verifying the form, returns HTTP200 {deliveries:[...]} from the original organization/workspace/form ledger. Optional submissionId and status filters narrow the query. Status is exactly pending,in_progress,accepted,delivered,failed or skipped; the direct HTTP route trims/validates it and returns400 invalid_delivery_status for an unsupported status. CLI/MCP validation should reject invalid enum input before execution.
Selected query sorts by created_at DESC then channel and takes LIMIT200. No cursor,total,nextCursor or paging mechanism is implemented. An empty array means no matching rows in this successful read;200 rows can be truncated history, not the entire ledger. Equal created_at/channel ties have no further stable ordering.
Every record maps id,submissionId,channel,status,attempts,lastError,detail,nextAttemptAt,deliveredAt,createdAt,updatedAt. attempts is numeric; detail_json is parsed with {} fallback. The mapper omits raw context_json,lease_token,lease_until and scope ids, but detail/lastError can still contain operational or subject-related information; keep real output private.
This handler only reads existing ledger rows. It does not enqueue, reset, run, reconcile, poll providers or decrypt response answers. Statuses describe stored channel processing; accepted/delivered are not blanket proof of email receipt, CRM correctness, consent validity, all-channel success or external business completion. A skipped or absent row is not equivalent to delivered.
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
Pending outbound record
Complete source-derived synthetic UNRUN HTTP200. One synthetic queued row exists with0attempts; it has not run. No provider, delivery or real respondent was accessed.
Input:
{
"formId": "forms_docs_fixture",
"submissionId": "formsubmission_docs_fixture",
"status": "pending"
}
Response:
{
"deliveries": [
{
"id": "formdelivery_docs_fixture",
"submissionId": "formsubmission_docs_fixture",
"channel": "outbound",
"status": "pending",
"attempts": 0,
"lastError": null,
"detail": {},
"nextAttemptAt": "2026-10-20T08:00:00.000Z",
"deliveredAt": null,
"createdAt": "2026-10-20T08:00:00.000Z",
"updatedAt": "2026-10-20T08:00:00.000Z"
}
]
}
Verify the real authorized scope and interpret only the documented response. Fictional identifiers and this example authorize no application operation.
No matching ledger rows
Complete source-derived synthetic UNRUN HTTP200. The form exists and the successful filtered query returns no failed rows. Other statuses/history may exist; no all-channel delivery claim.
Input:
{
"formId": "forms_docs_fixture",
"status": "failed"
}
Response:
{
"deliveries": []
}
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 the intended original scope and actual returned submission ids/channel filters. The response omits form/organization/workspace ids, so retain the bound request evidence.
-
Interpret at most200 stored rows and their exact statuses; reconcile a material provider outcome through an independently authorized source of truth. A read does not authorize a retry or new destination.
-
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. Retain actual failures; do not reset/retry channels, create submissions, change settings or contact providers to recover a ledger read.
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.