Authorization lifecycle

Documentation Index

Fetch the complete documentation index at: https://docs.trycollate.ai/llms.txt

Use this file to discover all available pages before exploring further.

An authorization moves through six lifecycle states. status says where the case is. nextAction says what the API expects you to do next when the case is yours.

​

Statuses

​

requires_input

At least one blocker is open. Inspect requirements.questions for unanswered fields, requirements.documents for missing files, and requirements.issues for validation errors. Resolve them through PATCH /answers and POST /attachments. When every blocker clears, the authorization moves to requires_confirmation.

​

requires_confirmation

The customer-owned step is confirmable. Send the current nextAction.id to POST /confirm. The accepted authorization moves to processing. Patching answers or removing attachments at this stage can reintroduce blockers and move the authorization back to requires_input.

​

processing

Collate owns the next move — discovery, filling, validation, submission, or follow-up. Read the authorization to learn the result. From processing, the authorization can transition to requires_input (more information needed), requires_confirmation (final approval needed), waiting_on_payer (payer receipt proven), or completed (terminal result observed).

​

waiting_on_payer

submission.payerReceipt is present and the payer has the next move. This is not an error. Keep reading the authorization until the payer responds with more information needed or a terminal decision.

​

completed

outcome is set. Read outcome and submission.decision for the terminal truth. Outcomes are approved, denied, modified, not_required, or failed.

​

canceled

The authorization was canceled locally. submission.payerReceipt and submission.decision are preserved on the snapshot. Future writes are rejected.

​

Next actions

​

provide_requirements

Pairs with requires_input. Resolve by patching answers and attaching files. Calling /confirm for this action returns 409 next_action_not_confirmable.

​

advance_case

Pairs with requires_confirmation. Resolve by sending the current nextAction.id to POST /confirm. Confirmation lets Collate continue processing from the current authorization version.

​

approve_submission

Pairs with requires_confirmation and only appears when policy.finalSubmission = requires_confirmation. The authorization carries a submission.reviewSnapshot describing the package Collate prepared. Render the snapshot, confirm with the current nextAction.id, and Collate crosses the final payer-submission boundary. See Final submission approval.

​

Final-submission policy

Every create includes policy.finalSubmission: automatic does not mean Collate starts processing on create. The first handoff from you to Collate is still confirm advance_case when the authorization exposes that action.

​

Transitions

​

Polling

The authorization itself is the canonical read model. Poll it on a steady cadence — every few seconds during a known-busy window, slower otherwise — and branch on status. There is no public execution, browser-run, or submission-attempt resource. When you want sub-second latency on customer-owned transitions, rely on webhooks once they ship. Until then, polling the authorization detail is the supported path.

​

Cancellation

POST /cancel stops further work on a non-terminal authorization. It does not reverse a payer submission already received. submission.payerReceipt and submission.decision are preserved on the canceled snapshot for audit.