Create a prior authorization
Create a new prior authorization. Provide exactly one of patient_id (existing id) or patient_data (inline demographics; server find-or-creates). Optionally provide one of payor_id or payor_data. New authorizations start in status=pending.
Authorizations
Body
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 payor_id (existing patient-payor id, validated to
belong to the resolved patient) or payor_data (inline; server links to
an existing payor row on the resolved patient that matches the catalog
id). If neither is provided and no payor exists on the patient for that
catalog id, the authorization is created without a linked payor.
Authorization category. assessment for an initial evaluation, treatment for ongoing services, reassessment for a renewed evaluation of an existing authorization, reassessment_and_treatment for a combined re-assessment plus continued-treatment request.
assessment, treatment, reassessment, reassessment_and_treatment "treatment"
Credentialing record id for the provider requesting the authorization.
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.
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, workflow automation, activity log). Mutually exclusive with patient_id.
Existing patient-payor id (must belong to the resolved patient and be active). Mutually exclusive with payor_data. Write-only resolution input — this id is used to derive and freeze the member id + insurance id onto the authorization at create time. It is NOT returned on the resource. To read payor information, use payor_member_id, payor_insurance_id, and payor_insurance on the response.
Inline payor reference by catalog id. The server looks up an existing payor row on the resolved patient that points to this catalog entry; if none, the authorization is created without a linked payor. Mutually exclusive with payor_id. Write-only resolution input — the resolved member id + insurance id are frozen onto the authorization as a snapshot. Read them back via payor_member_id, payor_insurance_id, and payor_insurance.
Requested service details (specialty, dates, CPT codes, places of service).
Credentialing record id for the servicing provider. Omit when the servicing provider is the same as the requesting provider.
Company-location id where services will be rendered.
Business entity (organization) this authorization belongs to. Optional.
Free-text notes attached to the authorization. Editable post-creation.
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.
"2025-02-01"
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).
Response
Successful Response
Response schema for a prior authorization record.
Authorization type.
assessment, treatment, reassessment, reassessment_and_treatment Lifecycle state of a prior authorization.
pending, in_review, extra_information_needed, decided, cancelled 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 as submitted on this authorization. Frozen at create time — not updated when the patient record changes.
Patient last name as submitted on this authorization. Frozen at create time.
Patient date of birth (YYYY-MM-DD) as submitted on this authorization. Frozen at create time.
Payor outcome on a decided authorization.
approved, partially_approved, denied, no_authorization_required 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.
requested, appealing, appeal_approved, appeal_denied, not_appealing Rationale captured when an appeal was requested. Null when no appeal has been requested.
Appeal case/reference number issued by the payor. Null until the payor assigns one.
Requester availability windows captured when an appeal was requested. Null when none provided.
Member id as submitted on this authorization. Frozen at create time.
Insurance partner id (from the insurances catalog) as submitted on this authorization. Frozen at create time.
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.
Credentialing-record id of the requesting provider. Always present unless the provider record was later removed (FK is ON DELETE SET NULL).
Credentialing-record id of the servicing provider. Null when the servicing provider is the same as the requesting provider or unset.
Company-location id where services are rendered. Null when unset.
Business entity (organization) this authorization belongs to. Null when unset.
Expanded requesting-provider object. Present ONLY when requested via expand[]=requesting_provider; null otherwise. Use requesting_provider_id for the reference.
Expanded servicing-provider object. Present ONLY when requested via expand[]=servicing_provider; null otherwise.
Expanded servicing-location object. Present ONLY when requested via expand[]=servicing_location; null otherwise.
Nested user (created_by) in response.
Service request details returned in the response.
See PriorAuthorizationResultResponse for the rationale on validation_alias.
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.
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.
Number of attached files. Always present (a cheap aggregate); independent of expand.
Last time staff followed up with the payor on this authorization's status. Null until the first follow-up.
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.
True when the clinic has marked this authorization done (it leaves the default list). Derived from completed_at.
When the authorization was marked done. Null while outstanding.
Id of the user who marked it done. Null while outstanding.
The user who marked it done (Solum staff identity is masked for customer viewers). Null while outstanding.