Authorization lifecycle | Collate API Documentation

Use this page when you need to understand ownership and transitions for a prior authorization case.

An Authorization moves through a small public state machine. Read the latest authorization and branch on status; use nextAction only when the case is waiting on you.

Statuses

`status`	Meaning	Customer action
`requires_action`	The case is waiting for your system or user.	Resolve `nextAction`.
`processing`	Collate owns discovery, portal work, validation, submission, or recovery.	Poll the authorization.
`waiting_on_payer`	Collate has payer receipt and the payer has the next move.	Poll for follow-up or terminal decision.
`completed`	The case has a terminal outcome.	Read `outcome` and `submission.decision`.
`canceled`	Local work was canceled.	Stop.

Act only when status = requires_action. Poll when Collate or the payer owns the next move. Stop writing after completed or canceled.

Next actions

nextAction is present only when status = requires_action.

`nextAction.type`	Resolution kind	What to do
`resolve_requirements`	`update_authorization`	Patch answers or attach files. Do not call `/confirm`.
`continue_authorization`	`confirm`	Call `POST /confirm` with `If-Match`.
`approve_submission`	`confirm`	Review `submission.reviewSnapshot`, then call `POST /confirm`.
`complete_payer_interaction`	`manual_handoff`	Use manual handoff endpoints.

nextAction.covers records the versions the action was issued against. You do not send the action ID back. The server checks the current state, If-Match, and review snapshot acknowledgement when needed.

Customer writes

requirements is the current blocker set. Answer and attachment writes:

are allowed only while the authorization is mutable
recompute requirements
can move the case between resolve_requirements, continue_authorization, and approve_submission
never resume Collate processing by themselves

When the updated authorization exposes continue_authorization or approve_submission, call /confirm.

Final submission

Every create request includes policy.finalSubmission.

Value	Meaning
`requires_approval`	Collate pauses before final payer submit and returns `approve_submission` when approval is needed.
`automatic`	Collate may submit at the final boundary without another customer approval in environments where final submit is enabled.

Sandbox and non-production safety gates may still pause at approve_submission. Treat policy.finalSubmission as policy, not as a replacement for reading nextAction.

Receipt and decision

submission.payerReceipt means Collate has evidence that the payer received the submission. After receipt, the case can enter waiting_on_payer.

submission.decision is terminal payer decision information when known. Terminal outcomes are approved, denied, modified, not_required, and failed.

Manual handoff

Manual handoff is a customer-owned payer interaction. It appears only when the authorization exposes complete_payer_interaction. During normal processing, live-session access is read-only and customers cannot interrupt automation with a handoff command.

After a manual handoff closes, Collate returns the authorization to processing while it reconciles payer evidence.

Cancellation

POST /cancel cancels local work on a non-terminal authorization. It does not undo payer-side work that already happened. Existing receipt and decision projections are preserved on the canceled snapshot.

Polling

The authorization detail endpoint is the supported public polling surface. Webhook delivery is not part of this public API yet. Use bounded polling and back off while Collate or the payer owns the next step.

Do not infer workflow ownership from internal executions, browser sessions, replay artifacts, portal claims, or raw runtime URLs. Public integrations branch on Authorization.status and Authorization.nextAction.