v1

latestOpenAPI 3.1.02026-07-2218105157.9 KB

Prior Authorizations

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.

post/v1/prior-authorizations

Request body

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

Authorization type.

patient_idstring uuid nullable

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.

payor_idstring uuid nullable

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.

requesting_provider_idstring uuid required

Credentialing record id for the provider requesting the authorization.

servicing_provider_idstring uuid nullable

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

servicing_location_idstring uuid nullable

Company-location id where services will be rendered.

organization_idstring uuid nullable

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

notesstring nullable

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

scheduled_submission_datestring date nullable

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.

copy_files_from_prior_authorization_idstring uuid nullable

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

Example request

{
  "patient_data": {
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01"
  },
  "payor_data": {
    "member_id": "ABC123456",
    "insurance_display_name": "Carolina Complete"
  },
  "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"
    ]
  },
  "scheduled_submission_date": "2025-02-01"
}

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.

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

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

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