Workflow states
| State | Meaning |
|---|---|
needs_input | Required case data or questionnaire answers are still missing. The authorization can be updated, previewed, and supplemented with attachments. |
ready_to_submit | Required data is present and no blocking actions are open. |
submitting | Transient state while the API renders documents, uploads them, and records the outbound submission. |
pending_payer | Submission completed successfully and the payer has not responded yet. |
action_required | A blocking action is open. This is either a system-generated validation issue or a payer request for information. |
completed | Terminal state. Check decisionState and decisionDetails for the payer outcome. |
cancelled | Terminal state. The authorization was cancelled before completion. |
Decision states
| State | Meaning |
|---|---|
unknown | No payer decision has been recorded. |
pending | The authorization has been submitted and is awaiting a payer response. |
approved | The payer approved the request. |
denied | The payer denied the request. |
Transition rules
| Current state | Operation or event | Result | Notes |
|---|---|---|---|
| — | POST /authorizations with incomplete required answers | needs_input | Creation succeeds even when required answers are missing. |
| — | POST /authorizations with complete required answers | ready_to_submit | The authorization is immediately submittable. |
needs_input | PATCH /authorizations/{id} with blockers cleared | ready_to_submit | Validation-issue actions are recomputed automatically. |
needs_input or ready_to_submit | PATCH /authorizations/{id} leaves blocking validation actions open | action_required | Validation-issue actions can appear during patch as well as during submit. |
needs_input | POST /authorizations/{id}/submit | action_required | Submit returns 409 validation_failed and creates validation_issue actions. |
ready_to_submit | POST /authorizations/{id}/submit | submitting then pending_payer | Submit is idempotent when you send an idempotency key. |
submitting | submission side effect fails | ready_to_submit | The API records a failed submission event and clears the transient state. |
pending_payer | sandbox or live approval | completed | decisionState becomes approved. |
pending_payer | sandbox or live denial | completed | decisionState becomes denied. |
pending_payer | sandbox or live payer request for information | action_required | Creates a payer_request_for_information action. |
action_required | client patches validation blockers | ready_to_submit if no other blocking actions remain | Applies to system-managed validation actions. |
action_required | client resolves payer request for information | ready_to_submit if no other blocking actions remain | Requires at least one attachment ID in the resolve request. |
needs_input, ready_to_submit, pending_payer, action_required | POST /authorizations/{id}/cancel | cancelled | Cancellation is blocked in terminal states. |
Submission semantics
POST /v1/prior-auth/authorizations/{authorizationId}/submit runs in three stages:
- validate the authorization, verify that no blocking actions are open, create or reuse the submit idempotency lock, and move the case to
submitting - render the filled form, submission cover sheet, and submission packet, then upload them
- persist the artifacts, confirm the outbound submission, set
submissionChannel, stampsubmittedAtif needed, and move the case topending_payer
ready_to_submit.
Action model
Actions are the explicit blocking work items on an authorization.validation_issue
- created automatically when blocking validation errors are present after patch or submit
- can represent missing questionnaire answers, missing top-level context, or other rule violations
- not manually resolvable
- cleared automatically when the authorization is patched so the blocking issues disappear
payer_request_for_information
- created when the payer requests more documentation after submission
- resolved with
POST /v1/prior-auth/authorizations/{authorizationId}/actions/{actionId}/resolve - requires at least one attached authorization attachment ID
- returns the authorization to
ready_to_submitonce all blocking actions are cleared
Preview semantics
POST /v1/prior-auth/authorizations/{authorizationId}/preview is an explicit generation command. It may render documents and refresh cached preview state, but it does not mutate the authorization lifecycle.
Preview returns:
submittablevalidationIssuescontextRequirementsquestionStatesactiveRequirementGroupssupportingDocumentRequestsmappingSummarydocuments.filledFormdocuments.draftPacket
Resolved questionnaire data
Authorization creation resolves the payer questionnaire and keeps it fixed for that authorization. Authorization responses include:- the FHIR
questionnaire supportingDocumentationGuidancecontextRequirementsquestionStatesactiveRequirementGroups- reduced
sourceFormmetadata provenance
Events
Events are the immutable lifecycle log for an authorization. Common event types include:| Event type | Meaning |
|---|---|
prior_auth.authorization.created | Authorization created |
prior_auth.authorization.updated | Authorization updated |
prior_auth.status.changed | Workflow or decision state changed |
prior_auth.attachments.added | Supporting document attached |
prior_auth.attachments.removed | Supporting document removed |
prior_auth.submission.submitted | Submission committed |
prior_auth.submission.failed | Submission side effect failed |
prior_auth.action.required | Blocking action created |
prior_auth.action.resolved | Blocking action resolved |
prior_auth.payer.response_received | Payer response received |
prior_auth.completed | Authorization reached a terminal decision |
Idempotency
POST /authorizations and POST /authorizations/{id}/submit accept an optional Idempotency-Key header.
Behavior:
- same create key + same request body: returns the existing authorization
- same create key + different request body: returns
409 idempotency_key_reused_with_different_request - same submit key + same authorization: returns the current submission result without duplicating artifacts
- same submit key + different authorization: returns
409 idempotency_key_reused_for_different_authorization
Sandbox testing
The customer-visible sandbox route is:POST /v1/sandbox/prior-auth/authorizations/{authorizationId}/payer-events
approvaldenialmore_info_request