v1

latestOpenAPI 3.1.02026-07-2218105157.9 KB

Prior Authorizations

Update a prior authorization

Update fields on an existing prior authorization. Transitioning status to submitted auto-stamps submitted_at; transitioning to decided requires decision to be set and auto-stamps decided_at. status is otherwise managed by Solum: external callers may only confirm submitted information (information_needed → pending, which re-queues the authorization for Solum to re-submit) or cancel an in-flight authorization (pending / submitted / information_needed → cancelled); other status changes return 403. appeal_status may only be set when decision is denied or partially_approved; external callers may only set it to requested or not_appealing, and only while the appeal is not yet in a working state (appealing, appeal_approved, appeal_denied) — attempts beyond that return 403. Result fields can only be set when status is (or is transitioning to) decided — except the authorization number, the per-CPT authorization numbers, the reference number, and the authorized CPT codes, which may be set in any status (payors issue these at submission time, before a formal decision).

patch/v1/prior-authorizations/{id}

Path parameters

idstring required

Request body

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

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

Free-text rationale for the appeal request (captured when the appeal is requested). External callers may only set it while the appeal is not yet in a working state — 403 afterwards.

appeal_numberstring nullable

Appeal case/reference number issued by the payor once the appeal is filed. Managed internally — external callers receive 403 when setting it. Cleared automatically when appeal_status is cleared.

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

Authorization type.

notesstring nullable

Update top-level notes.

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 for the cancellation. Optional, except required when cancellation_reason is other.

completedboolean nullable

Clinic-owned completion flag. true marks the authorization done (it drops out of the default list); false reopens it. Independent of status — settable in any state. Stamps who/when on the server.

requesting_provider_idstring uuid nullable

Update requesting provider.

servicing_provider_idstring uuid nullable

Update servicing provider.

servicing_location_idstring uuid nullable

Update servicing location.

organization_idstring uuid nullable

Update the business entity (organization). Set to null to clear.

scheduled_submission_datestring date nullable

Date this authorization should be submitted (YYYY-MM-DD). Editable only while status is pending (403 afterwards for external callers). Set to null to clear the scheduled date.

Example request

{
  "appeal_availability": [
    {
      "day": "monday",
      "start": "15:00",
      "end": "17:00"
    }
  ],
  "scheduled_submission_date": "2025-02-01",
  "service": {
    "service_type_codes": [
      "AS"
    ],
    "start_date": "2025-01-01",
    "end_date": "2025-12-31",
    "cpt_codes": [
      {
        "code": "97153",
        "units": "160"
      }
    ],
    "requested_visits": 20,
    "requested_weeks": 8,
    "locations": [
      "office",
      "home"
    ]
  }
}

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.

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).

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"
    }
  ]
}