Skip to main content
POST
Create a prior authorization

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Create a prior authorization.

Provide exactly one of patient_id (existing patient id) or patient_data (inline demographics; server find-or-creates).

Optionally provide one of patient_policy_id (one of the resolved patient's active coverages) or policy_data (inline; server matches it to the resolved patient's active policy on that catalog id). If neither is provided, or no policy on the patient matches, the authorization is created without a linked coverage.

​
type
enum<string>
required

Authorization category. assessment for the initial assessment, before there is a treatment plan; treatment for the therapy a first treatment plan requests; reassessment for re-evaluating a patient already in treatment when no continued therapy is requested; reassessment_and_treatment for a renewal that requests continued therapy.

Available options:
assessment,
treatment,
reassessment,
reassessment_and_treatment
Example:

"treatment"

​
requesting_provider_id
string<uuid>
required

Credentialing record id for the provider requesting the authorization.

​
patient_id
string<uuid> | null

Existing patient id. When provided, the patient is looked up by id (must belong to your company and be active). Mutually exclusive with patient_data.

​
patient_data
PatientInlineData · object | null

Inline demographics for find-or-create resolution. The server looks up an existing patient by (first_name, last_name, date_of_birth); if not found, a new patient is created and normal patient-created side effects fire (webhook, integration sync, activity log). Mutually exclusive with patient_id.

​
patient_policy_id
string<uuid> | null

Existing patient-policy id (an active coverage of the resolved patient). Mutually exclusive with policy_data. Write-only resolution input — this id is used to derive and freeze the member number + insurance id onto the authorization at create time. It is NOT returned on the resource. To read the coverage, use payor_member_id, payor_insurance_id, and payor_insurance on the response.

​
policy_data
PolicyInlineData · object | null

Inline coverage reference by catalog id. The server matches it to the resolved patient's active policy on this catalog entry; if none, the inline values are recorded as submitted. Mutually exclusive with patient_policy_id. Write-only resolution input — the resolved member number + insurance id are frozen onto the authorization as a snapshot. Read them back via payor_member_id, payor_insurance_id, and payor_insurance.

​
service
ServiceBlock · object | null

Requested service details (specialty, dates, CPT codes, places of service).

​
servicing_provider_id
string<uuid> | null

Credentialing record id for the servicing provider. Omit when the servicing provider is the same as the requesting provider.

​
servicing_location_id
string<uuid> | null

Company-location id where services will be rendered.

​
organization_id
string<uuid> | null

Business entity (organization) this authorization belongs to. Optional.

​
notes
string | null

Free-text notes attached to the authorization. Editable post-creation.

​
external_id
string | null

This authorization's identifier in your own system, for correlating records across systems. Free text; not required to be unique. Surrounding whitespace is trimmed and an empty value is stored as null. Editable post-creation.

Maximum string length: 255
Example:

"EHR-PA-123"

​
scheduled_submission_date
string<date> | null

Date this authorization should be submitted (YYYY-MM-DD). When set in the future, the request is held out of the active review queue until that date. Omit or send null to submit whenever it is picked up.

Example:

"2025-02-01"

​
copy_files_from_prior_authorization_id
string<uuid> | null

When set, the new authorization is seeded with copies of the attached documents from this existing authorization (which must belong to your company). Each document is re-linked as a new file record pointing at the same stored object — the source authorization keeps its own copies. Used to duplicate an authorization (e.g. an assessment into a treatment).

​
request_vob
boolean | null

Request a verification of benefits (VOB) of this authorization's insurance with its services. Omit to follow your company's default. The insurance is saved on the patient either way when the patient has no matching policy. A VOB that can't be requested (an open one exists, or a detail is missing) never fails the authorization: its vob block says what is left.

​
vob_specialties
SpecialtyIn · object[] | null

The services the requested VOB verifies, as POST /v1/verification-of-benefits takes them. Omitted: this authorization's own service, CPT codes and places of service, billed under its servicing provider (else its requesting provider), with anything it lacks from your company's defaults. Used only when a VOB is requested, but validated with the rest of the body: an empty list or a malformed entry (an unknown key or service type, a credentialing_id that isn't a UUID, more than 50 CPT codes) fails the request with 422. A well-formed entry that can't be resolved never fails the authorization: its vob block says what is left.

Minimum array length: 1

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.