---
title: "Update a prior authorization"
method: PATCH
path: "/v1/prior-authorizations/{id}"
tags: ["Prior Authorizations"]
---

# Update a prior authorization

`PATCH /v1/prior-authorizations/{id}`

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

## Path parameters

- `id` string, required

## Request body

- PriorAuthorizationUpdateRequest — Update an existing prior authorization. State-machine transitions: - `status=submitted` automatically stamps `submitted_at` if unset. - `status=decided` requires a non-null `decision`; stamps `decided_at` if unset. - `appeal_status` may only be set when `decision` is `denied` or `partially_approved`.
  - `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_notes` string, 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_number` string, 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.
  - `appeal_availability` AppealAvailabilitySlot[], nullable — Requester availability windows for the appeal (e.g. peer-to-peer slots). External callers may only set it while the appeal is not yet in a working state — 403 afterwards. Set to `null` to clear; cleared automatically when `appeal_status` is cleared.
    - `day` string, required — Lowercase weekday, e.g. `monday`.
    - `start` string, required — Window start time, 24-hour `HH:MM`.
    - `end` string, required — Window end time, 24-hour `HH:MM`.
  - `type` 'assessment' | 'treatment' | 'reassessment' | 'reassessment_and_treatment' — Authorization type.
  - `notes` string, nullable — Update top-level notes.
  - `cancellation_reason` 'duplicate_already_submitted' | 'no_longer_needed' | 'submitted_directly_to_payor' | 'patient_no_longer_active' | 'entered_in_error' | 'other' — 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_note` string, nullable — Free-text detail for the cancellation. Optional, except required when `cancellation_reason` is `other`.
  - `completed` boolean, 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_id` string, uuid, nullable — Update requesting provider.
  - `servicing_provider_id` string, uuid, nullable — Update servicing provider.
  - `servicing_location_id` string, uuid, nullable — Update servicing location.
  - `organization_id` string, uuid, nullable — Update the business entity (organization). Set to null to clear.
  - `scheduled_submission_date` string, 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.
  - `service` ServiceBlock — Service request details. Captures what the requester is asking the payor to authorize.
    - `specialty` 'aba' | 'speech_therapy' | 'occupational_therapy' | 'physical_therapy' | 'mental_behavioral_health' — Clinical specialty the authorization covers.
    - `service_type_codes` string[], nullable — Free-form service type codes as defined by the payor's coverage catalog (e.g. `AS`, `WK`). Pass-through identifiers — not validated against an internal enum.
    - `start_date` string, date, nullable — Requested service start date (`YYYY-MM-DD`).
    - `end_date` string, date, nullable — Requested service end date (`YYYY-MM-DD`). Send `null` for open-ended requests where the payor will set the end date in the approval.
    - `cpt_codes` ServiceCptCode[], nullable — Requested CPT/HCPCS codes paired with unit counts.
      - `code` string, required — CPT or HCPCS procedure code.
      - `units` string, required — Quantity for this code. Stored as a string because some payors permit non-integer quantities (e.g. `0.5` hours of evaluation).
      - `unit_type` 'units' | 'visits' | 'hours' — Quantity unit a CPT/HCPCS line is measured in. Lives inside the `service_cpt_codes` / `result_cpt_codes` JSON (not a dedicated column), so this is a plain str Enum with no `__pg_type__`. Old rows predate the field — readers default a missing value to `units`. Wire values mirror the Prisma `PriorAuthorizationUnitType` enum (`units` / `visits` / `hours`); keep them in sync by hand (the `...Enum` suffix here intentionally keeps this out of `verify-enum-sync`'s name-matched set, same as the other PA enums).
      - `modifiers` CptModifier[], nullable — CPT/HCPCS modifiers that apply to this code (e.g. `95`, `GT`). Optional — entries created before this field existed omit it and read back as `None`.
    - `requested_visits` integer, nullable — Requested number of visits. Optional — used by therapy disciplines (physical / occupational / speech therapy) whose authorizations are granted by visit count rather than a fixed coverage block. Decoupled from `cpt_codes` (a payor may authorize visits with no CPT code).
    - `requested_weeks` integer, nullable — Requested number of weeks the services span. Optional — captured alongside `requested_visits` for visit-based therapy authorizations. Does not drive the end date.
    - `locations` PlaceOfService[], nullable — Places of service requested for this authorization (CMS POS categories).
  - `result` PriorAuthorizationResultUpdate — Result fields settable via PATCH when `status` transitions to `decided`.
    - `start_date` string, date, nullable — Authorized service start date.
    - `end_date` string, date, nullable — Authorized service end date.
    - `approved_visits` integer, nullable — Authorized number of visits.
    - `approved_weeks` integer, nullable — Authorized number of weeks.
    - `cpt_codes` ServiceCptCode[], nullable — Authorized CPT/HCPCS codes with unit counts.
      - `code` string, required — CPT or HCPCS procedure code.
      - `units` string, required — Quantity for this code. Stored as a string because some payors permit non-integer quantities (e.g. `0.5` hours of evaluation).
      - `unit_type` 'units' | 'visits' | 'hours' — Quantity unit a CPT/HCPCS line is measured in. Lives inside the `service_cpt_codes` / `result_cpt_codes` JSON (not a dedicated column), so this is a plain str Enum with no `__pg_type__`. Old rows predate the field — readers default a missing value to `units`. Wire values mirror the Prisma `PriorAuthorizationUnitType` enum (`units` / `visits` / `hours`); keep them in sync by hand (the `...Enum` suffix here intentionally keeps this out of `verify-enum-sync`'s name-matched set, same as the other PA enums).
      - `modifiers` CptModifier[], nullable — CPT/HCPCS modifiers that apply to this code (e.g. `95`, `GT`). Optional — entries created before this field existed omit it and read back as `None`.
    - `locations` PlaceOfService[], nullable — Authorized places of service.
    - `authorization_number` string, nullable — Authorization number issued by the payor.
    - `cpt_authorization_numbers` object, nullable — Per-procedure-code authorization numbers, for payors that issue a distinct number per code. Map of CPT/HCPCS code → authorization number (one number per code). Entered at submission time; settable in any status. When a code has no per-code number, the top-level `authorization_number` applies.
    - `reference_number` string, nullable — Secondary reference/tracking number issued by the payor, distinct from the authorization number.
    - `notes` string, nullable — Free-text notes about the payor's decision.

## Response `200`

Successful Response

- PriorAuthorizationResponse — Response schema for a prior authorization record.
  - `id` string, uuid, required
  - `company_id` string, uuid, required
  - `created_by_user_id` string, 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_notes` string, nullable — Rationale captured when an appeal was requested. Null when no appeal has been requested.
  - `appeal_number` string, nullable — Appeal case/reference number issued by the payor. Null until the payor assigns one.
  - `appeal_availability` AppealAvailabilitySlot[], nullable — Requester availability windows captured when an appeal was requested. Null when none provided.
    - `day` string, required — Lowercase weekday, e.g. `monday`.
    - `start` string, required — Window start time, 24-hour `HH:MM`.
    - `end` string, required — Window end time, 24-hour `HH:MM`.
  - `notes` string, nullable
  - `patient_id` string, 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_name` string, required — Patient first name as submitted on this authorization. Frozen at create time — not updated when the patient record changes.
  - `patient_last_name` string, required — Patient last name as submitted on this authorization. Frozen at create time.
  - `patient_date_of_birth` string, date, required — Patient date of birth (`YYYY-MM-DD`) as submitted on this authorization. Frozen at create time.
  - `payor_member_id` string, nullable — Member id as submitted on this authorization. Frozen at create time.
  - `payor_insurance_id` string, uuid, nullable — Insurance partner id (from the `insurances` catalog) as submitted on this authorization. Frozen at create time.
  - `payor_insurance_display_name` string, nullable — Plan display name for this PA's payor, frozen at create time. Null ⇒ display the insurance's canonical name.
  - `payor_insurance` PriorAuthorizationInsurance — Nested insurance partner ({id, name}) for the FROZEN snapshot. Resolved from the `payor_insurance` relationship, which loads regardless of the insurance's `is_active` flag — so a PA submitted under a since- deactivated insurance still carries its name for display.
    - `id` string, uuid, required
    - `name` string, required
    - `trading_partner_service_id` string, nullable — Trading partner service ID for this insurance, when mapped. Lets the client resolve the payer logo from the payer directory. Null when the insurance has no trading partner mapping.
  - `requesting_provider_id` string, 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_id` string, 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_id` string, uuid, nullable — Company-location id where services are rendered. Null when unset.
  - `organization_id` string, uuid, nullable — Business entity (organization) this authorization belongs to. Null when unset.
  - `requesting_provider` PriorAuthorizationProvider — Nested provider (credentialing record) in response.
    - `id` string, uuid, required
    - `name` string, required
    - `npi` string, required
    - `tax_id` string, nullable
    - `type` string, required
    - `is_active` boolean, required
    - `location` PriorAuthorizationProviderLocation — Nested location reference inside a credentialing record.
      - `id` string, uuid, required
      - `name` string, required
  - `servicing_provider` PriorAuthorizationProvider — Nested provider (credentialing record) in response.
    - `id` string, uuid, required
    - `name` string, required
    - `npi` string, required
    - `tax_id` string, nullable
    - `type` string, required
    - `is_active` boolean, required
    - `location` PriorAuthorizationProviderLocation — Nested location reference inside a credentialing record.
      - `id` string, uuid, required
      - `name` string, required
  - `servicing_location` PriorAuthorizationServicingLocation — Nested servicing location (full address) in response.
    - `id` string, uuid, required
    - `name` string, required
    - `address` string, required
    - `address_2` string, nullable
    - `city` string, required
    - `state` string, required
    - `zip_code` string, required
  - `created_by_user` PriorAuthorizationUser — Nested user (created_by) in response.
    - `id` string, required
    - `name` string, nullable
    - `email` string, nullable
    - `image` string, nullable
    - `user_type` string, nullable
  - `service` PriorAuthorizationServiceResponse — Service request details returned in the response. See `PriorAuthorizationResultResponse` for the rationale on `validation_alias`.
    - `specialty` 'aba' | 'speech_therapy' | 'occupational_therapy' | 'physical_therapy' | 'mental_behavioral_health' — Clinical specialty the authorization covers.
    - `service_type_codes` string[], nullable
    - `start_date` string, date, nullable
    - `end_date` string, date, nullable
    - `requested_visits` integer, nullable
    - `requested_weeks` integer, nullable
    - `cpt_codes` ServiceCptCode[], nullable
      - `code` string, required — CPT or HCPCS procedure code.
      - `units` string, required — Quantity for this code. Stored as a string because some payors permit non-integer quantities (e.g. `0.5` hours of evaluation).
      - `unit_type` 'units' | 'visits' | 'hours' — Quantity unit a CPT/HCPCS line is measured in. Lives inside the `service_cpt_codes` / `result_cpt_codes` JSON (not a dedicated column), so this is a plain str Enum with no `__pg_type__`. Old rows predate the field — readers default a missing value to `units`. Wire values mirror the Prisma `PriorAuthorizationUnitType` enum (`units` / `visits` / `hours`); keep them in sync by hand (the `...Enum` suffix here intentionally keeps this out of `verify-enum-sync`'s name-matched set, same as the other PA enums).
      - `modifiers` CptModifier[], nullable — CPT/HCPCS modifiers that apply to this code (e.g. `95`, `GT`). Optional — entries created before this field existed omit it and read back as `None`.
    - `locations` PlaceOfService[], nullable
  - `result` PriorAuthorizationResultResponse — Payor decision details. Populated only when `status` is `decided`. Uses `validation_alias` (not `alias`) so the alias only applies to input (reading the parent PA's `result_start_date` etc. columns via `from_attributes`). Output uses the field name; otherwise FastAPI's `response_model_by_alias=True` default would leak the column-prefixed name onto the wire and the frontend would see `resultStartDate` after `transformFromAPI` instead of the expected `startDate`.
    - `start_date` string, date, nullable
    - `end_date` string, date, nullable
    - `approved_visits` integer, nullable
    - `approved_weeks` integer, nullable
    - `cpt_codes` ServiceCptCode[], nullable
      - `code` string, required — CPT or HCPCS procedure code.
      - `units` string, required — Quantity for this code. Stored as a string because some payors permit non-integer quantities (e.g. `0.5` hours of evaluation).
      - `unit_type` 'units' | 'visits' | 'hours' — Quantity unit a CPT/HCPCS line is measured in. Lives inside the `service_cpt_codes` / `result_cpt_codes` JSON (not a dedicated column), so this is a plain str Enum with no `__pg_type__`. Old rows predate the field — readers default a missing value to `units`. Wire values mirror the Prisma `PriorAuthorizationUnitType` enum (`units` / `visits` / `hours`); keep them in sync by hand (the `...Enum` suffix here intentionally keeps this out of `verify-enum-sync`'s name-matched set, same as the other PA enums).
      - `modifiers` CptModifier[], nullable — CPT/HCPCS modifiers that apply to this code (e.g. `95`, `GT`). Optional — entries created before this field existed omit it and read back as `None`.
    - `locations` PlaceOfService[], nullable
    - `authorization_number` string, nullable
    - `cpt_authorization_numbers` object, nullable
    - `reference_number` string, nullable
    - `notes` string, nullable
    - `ai_summary` string, nullable
    - `ai_summary_generated_at` string, date-time, nullable
  - `files` PriorAuthorizationFile[], nullable — Attached files with signed download URLs. Present ONLY on `GET /{id}` with `expand[]=files`; always `null` on the list endpoint (use `file_count` there). Signed URLs are minted only when this is expanded.
    - `id` string, uuid, required
    - `name` string, required
    - `display_name` string, nullable
    - `path` string, required
    - `type` string, nullable
    - `size` integer, nullable
    - `document_type` 'referral' | 'authorization' | 'intake_documents' | 'legal_documents' | 'financial_documents' | 'insurance_card' | 'billing' | 'spam' | 'plan_of_care' | 'diagnosis' | 'medical_records' | 'other' — Document type enum matching Prisma @map values. Bound to PG enum `fax_type`.
    - `metadata` object, nullable
    - `created_at` string, date-time, required
    - `url` string, nullable
  - `file_count` integer, nullable — Number of attached files. Always present (a cheap aggregate); independent of `expand`.
  - `submitted_at` string, date-time, nullable
  - `decided_at` string, date-time, nullable
  - `appeal_submitted_at` string, 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_at` string, date-time, nullable — Last time staff followed up with the payor on this authorization's status. Null until the first follow-up.
  - `scheduled_submission_date` string, 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.
  - `completed` boolean — True when the clinic has marked this authorization done (it leaves the default list). Derived from `completed_at`.
  - `completed_at` string, date-time, nullable — When the authorization was marked done. Null while outstanding.
  - `completed_by_user_id` string, nullable — Id of the user who marked it done. Null while outstanding.
  - `completed_by_user` PriorAuthorizationUser — Nested user (created_by) in response.
    - `id` string, required
    - `name` string, nullable
    - `email` string, nullable
    - `image` string, nullable
    - `user_type` string, nullable
  - `cancellation_reason` 'duplicate_already_submitted' | 'no_longer_needed' | 'submitted_directly_to_payor' | 'patient_no_longer_active' | 'entered_in_error' | 'other' — 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_note` string, nullable — Free-text detail captured with the cancellation reason. Null when none was provided.
  - `cancelled_at` string, date-time, nullable — When the authorization was cancelled. Null unless the authorization is cancelled.
  - `active` boolean, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400` — Validation error
- `401` — Authentication required
- `403` — Forbidden — appeal fields are restricted for external callers
- `404` — Not found
- `409` — Conflict — resource already exists
- `422` — Validation Error

---

[API](https://skmtc.net/getsolum/apis/solum-health-api.md) · [All operations](https://skmtc.net/getsolum/apis/solum-health-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getsolum/solum-health-api/versions/2bf886cdf729/schema)