Skip to main content
PATCH
Update a prior authorization

Authorizations

​
X-API-Key
string
header
required

Path Parameters

​
id
string
required

Body

application/json
​
type
enum<string> | null

Authorization type.

Available options:
assessment,
treatment,
reassessment,
reassessment_and_treatment
​
notes
string | null
​
external_id
string | null
Maximum string length: 255
​
cancellation_reason
enum<string> | null

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.

Available options:
duplicate_already_submitted,
no_longer_needed,
submitted_directly_to_payor,
patient_no_longer_active,
entered_in_error,
other
​
cancellation_note
string | null
​
completed
boolean | null
​
requesting_provider_id
string<uuid> | null
​
servicing_provider_id
string<uuid> | null
​
servicing_location_id
string<uuid> | null
​
organization_id
string<uuid> | null
​
scheduled_submission_date
string<date> | null
​
service
ServiceBlock · object | null

Service request details. Captures what the requester is asking the payor to authorize, plus request-side context the payor evaluates it against (visits_last_90_days — prior utilization, not part of the ask).

​
status
enum<string> | null

Lifecycle state of a prior authorization.

Available options:
pending,
submitted,
information_needed,
decided,
cancelled
​
appeal_status
enum<string> | null
Available options:
requested,
not_appealing
​
appeal_notes
string | null
​
appeal_availability
AppealAvailabilitySlot · object[] | null
​
request_vob
boolean | null

Whether this authorization still asks for a verification of benefits (VOB) of its insurance. false finishes it without one; true asks again. Allowed in any status. It requests nothing by itself: request the VOB with POST /v1/verification-of-benefits and this authorization's id in prior_authorization_id.

Response

Successful Response

No inheritance from the staff response: new private fields stay private.

​
id
string<uuid>
required
​
company_id
string<uuid>
required
​
type
enum<string>
required

Authorization type.

Available options:
assessment,
treatment,
reassessment,
reassessment_and_treatment
​
status
enum<string>
required

Lifecycle state of a prior authorization.

Available options:
pending,
submitted,
information_needed,
decided,
cancelled
​
patient_id
string<uuid>
required
​
patient_first_name
string
required
​
patient_last_name
string
required
​
patient_date_of_birth
string<date>
required
​
active
boolean
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
created_by_user_id
string | null
​
decision
enum<string> | null

Payor outcome on a decided authorization.

Available options:
approved,
partially_approved,
denied,
no_authorization_required
​
appeal_status
enum<string> | null

Appeal lifecycle. An appeal STARTS from a denied or partially_approved decision; the terminal states below outlive it, because a won appeal is exactly one whose decision is no longer a denial.

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 — an appeal has been requested; work has not started. appealing — Solum is actively working the appeal. appeal_approved — terminal, won outright. appeal_partially_approved — terminal, won in part (payor granted less than requested). appeal_denied — terminal, lost. not_appealing — terminal, operator decided not to pursue.

The won/partial/lost outcomes mirror the granularity of PriorAuthorizationDecisionEnum: a payor that grants less than was requested on appeal has partially granted it.

Available options:
requested,
appealing,
appeal_approved,
appeal_partially_approved,
appeal_denied,
not_appealing
​
appeal_notes
string | null
​
appeal_number
string | null
​
appeal_availability
AppealAvailabilitySlot · object[] | null
​
notes
string | null
​
external_id
string | null
​
payor_member_id
string | null
​
payor_insurance_id
string<uuid> | null
​
payor_insurance_display_name
string | null
​
payor_insurance
PriorAuthorizationInsurance · object | null

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.

​
requesting_provider_id
string<uuid> | null
​
servicing_provider_id
string<uuid> | null
​
servicing_location_id
string<uuid> | null
​
organization_id
string<uuid> | null
​
requesting_provider
PriorAuthorizationProvider · object | null

Nested provider (credentialing record) in response.

​
servicing_provider
PriorAuthorizationProvider · object | null

Nested provider (credentialing record) in response.

​
servicing_location
PriorAuthorizationServicingLocation · object | null

Nested servicing location (full address) in response.

​
created_by_user
PriorAuthorizationUser · object | null

Nested user (created_by) in response.

​
service
PriorAuthorizationServiceResponse · object | null

Service request details returned in the response.

See PriorAuthorizationResultResponse for the rationale on validation_alias.

​
result
PriorAuthorizationResultResponse · object | null

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.

​
files
PriorAuthorizationFile · object[] | null
​
file_count
integer | null
​
submitted_at
string<date-time> | null
​
decided_at
string<date-time> | null
​
appeal_submitted_at
string<date-time> | null
​
last_followed_up_at
string<date-time> | null
​
scheduled_submission_date
string<date> | null
​
completed
boolean
default:false
​
completed_at
string<date-time> | null
​
completed_by_user_id
string | null
​
completed_by_user
PriorAuthorizationUser · object | null

Nested user (created_by) in response.

​
cancellation_reason
enum<string> | null

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.

Available options:
duplicate_already_submitted,
no_longer_needed,
submitted_directly_to_payor,
patient_no_longer_active,
entered_in_error,
other
​
cancellation_note
string | null
​
cancelled_at
string<date-time> | null
​
vob
PriorAuthorizationVob · object | null

The verification of benefits of this authorization's insurance; null when it names none. Only single reads carry it (retrieve, create, update): list rows return null.