Authorization object | Collate API Documentation

Authorization is the source of truth for a prior authorization case. Build your integration around reading this object, branching on status and nextAction, and using version for optimistic concurrency.

Top-level fields

Field	Meaning
`id`	Stable authorization ID.
`version`	Integer version for `If-Match` on mutable operations.
`status`	Lifecycle state: `requires_action`, `processing`, `waiting_on_payer`, `completed`, or `canceled`.
`outcome`	Terminal result when `status = completed`: `approved`, `denied`, `modified`, `not_required`, or `failed`.
`policy.finalSubmission`	Final payer-submit policy selected at create time.
`providerNpi`	Tenant-scoped provider NPI used for routing.
`payer`	Canonical payer destination.
`request`	Payer, coverage state, service type, and service code.
`route`	Resolved channel route. Public routes are `portal` with `collate_managed` access.
`questionnaire`	Current compact recursive answerable surface.
`answers`	Current normalized nested answer set.
`requirements`	Current unresolved blockers.
`attachments`	Supporting documents linked to the authorization.
`submission`	Review snapshot, payer receipt, and terminal decision projections.
`nextAction`	Current customer-owned action, or `null`.
`activeManualHandoff`	Pointer to an active manual handoff, when one exists.
`metadata`	Customer metadata supplied on create.
`createdAt`, `updatedAt`, `completedAt`, `canceledAt`	Timestamps for audit and display.

Status and nextAction

status says who owns the next move. nextAction says exactly what to do when status = requires_action.

`nextAction.type`	`nextAction.resolution.kind`	Resolve with
`resolve_requirements`	`update_authorization`	`PATCH /answers`, file upload, and attachment writes.
`continue_authorization`	`confirm`	`POST /confirm` with `If-Match`.
`approve_submission`	`confirm`	Review `submission.reviewSnapshot`, then `POST /confirm`.
`complete_payer_interaction`	`manual_handoff`	Manual handoff endpoints.

nextAction.covers tells you which authorization, requirements, answers, attachments, and review snapshot versions the action was issued against. You do not echo action IDs into command requests. The server derives the current action from state and rejects stale writes with version_conflict or review_stale.

Requirements

requirements is a blocker set:

1 {
2   "version": 3,
3   "questions": [
4     {
5       "linkId": "code",
6       "path": "diagnoses[0].code",
7       "message": "Diagnosis Code is required."
8     }
9   ],
10   "documents": [
11     { "type": "clinical_notes", "message": "Clinical notes are required." }
12   ],
13   "issues": []
14 }

An empty requirements object does not always mean the case should advance automatically. Branch on nextAction.

Submission

submission separates review, receipt, and decision truth.

Field	Meaning
`reviewSnapshot`	Package Collate prepared for final approval. Present when `approve_submission` is open.
`payerReceipt`	Evidence-backed proof that the payer received the submission.
`decision`	Terminal payer decision when known.

waiting_on_payer means payerReceipt is present and the payer has the next move. completed means outcome is set and decision contains terminal decision details when a payer decision exists.

Not public resources

Do not build against internal executions, browser runs, replay artifacts, portal claims, reconciliation rows, or internal provider-session URLs. They are internal implementation details. Public integrations use Authorization, File, route/catalog endpoints, live-session grants, and manual handoff endpoints.