v1

latestOpenAPI 3.1.02026-07-2218105157.9 KB

Prior Authorizations

Retrieve a prior authorization

Return a single prior authorization by id, including nested patient, payor, providers, location, service block, result block, and attached files (with signed URLs).

get/v1/prior-authorizations/{id}

Path parameters

idstring required

Query parameters

expand[]PriorAuthorizationExpand[] nullable

Relations to inline in the response. Repeatable, e.g. ?expand[]=files&expand[]=servicing_location.

Response

Successful Response

idstring uuid required

company_idstring uuid required

created_by_user_idstring nullable

type'assessment' | 'treatment' | 'reassessment' | 'reassessment_and_treatment' required

Authorization type.

status'pending' | 'submitted' | 'information_needed' | 'decided' | 'cancelled' required

Lifecycle state of a prior authorization.

decision'approved' | 'partially_approved' | 'denied' | 'no_authorization_required'

Payor outcome on a decided authorization.

appeal_status'requested' | 'appealing' | 'appeal_approved' | 'appeal_denied' | 'not_appealing'

Appeal lifecycle. Applies only when decision is denied or partially_approved.

NULL is meaningful: it means no appeal decision has been made yet — the caller hasn't yet asked for one. Setting any value below is an explicit commitment that someone is (or isn't) pursuing the appeal:

requested — operator/patient asked for an appeal; team hasn't started. appealing — team is actively working the appeal. appeal_approved — terminal, won. appeal_denied — terminal, lost. not_appealing — terminal, operator decided not to pursue.

appeal_notesstring nullable

Rationale captured when an appeal was requested. Null when no appeal has been requested.

appeal_numberstring nullable

Appeal case/reference number issued by the payor. Null until the payor assigns one.

notesstring nullable

patient_idstring uuid required

Patient this authorization belongs to; use it to open the patient record. Demographics submitted on this PA are the frozen patient_* fields below.

patient_first_namestring required

Patient first name as submitted on this authorization. Frozen at create time — not updated when the patient record changes.

patient_last_namestring required

Patient last name as submitted on this authorization. Frozen at create time.

patient_date_of_birthstring date required

Patient date of birth (YYYY-MM-DD) as submitted on this authorization. Frozen at create time.

payor_member_idstring nullable

Member id as submitted on this authorization. Frozen at create time.

payor_insurance_idstring uuid nullable

Insurance partner id (from the insurances catalog) as submitted on this authorization. Frozen at create time.

payor_insurance_display_namestring nullable

Plan display name for this PA's payor, frozen at create time. Null ⇒ display the insurance's canonical name.

requesting_provider_idstring uuid nullable

Credentialing-record id of the requesting provider. Always present unless the provider record was later removed (FK is ON DELETE SET NULL).

servicing_provider_idstring uuid nullable

Credentialing-record id of the servicing provider. Null when the servicing provider is the same as the requesting provider or unset.

servicing_location_idstring uuid nullable

Company-location id where services are rendered. Null when unset.

organization_idstring uuid nullable

Business entity (organization) this authorization belongs to. Null when unset.

file_countinteger nullable

Number of attached files. Always present (a cheap aggregate); independent of expand.

submitted_atstring date-time nullable

decided_atstring date-time nullable

appeal_submitted_atstring date-time nullable

When the appeal was submitted to the payor; set when the appeal first becomes active. Null when no appeal has been submitted.

last_followed_up_atstring date-time nullable

Last time staff followed up with the payor on this authorization's status. Null until the first follow-up.

scheduled_submission_datestring date nullable

Date this authorization should be submitted to the payor. When set in the future, the request is held out of the active review queue until that date. Null when no scheduled date is set.

completedboolean

True when the clinic has marked this authorization done (it leaves the default list). Derived from completed_at.

completed_atstring date-time nullable

When the authorization was marked done. Null while outstanding.

completed_by_user_idstring nullable

Id of the user who marked it done. Null while outstanding.

Why a prior authorization was cancelled — captured on every transition into cancelled. other is the escape hatch (the free-text detail then lives in cancellation_note).

Keep the members in sync with the Prisma enum PriorAuthorizationCancellationReason (apps/frontend/prisma/schema/enums.prisma) and the frontend label map PRIOR_AUTH_CANCELLATION_REASON_LABELS. verify-enum-sync only compares UPPERCASE Python members, so — like PriorAuthorizationStatusEnum — this lowercase enum is NOT covered by that check; sync it by hand.

cancellation_notestring nullable

Free-text detail captured with the cancellation reason. Null when none was provided.

cancelled_atstring date-time nullable

When the authorization was cancelled. Null unless the authorization is cancelled.

activeboolean required

created_atstring date-time required

updated_atstring date-time required

Example response

{
  "appeal_availability": [
    {
      "day": "monday",
      "start": "15:00",
      "end": "17:00"
    }
  ]
}