Prior Authorization

HealOS prepares prior authorizations on two tracks:

CoverMyMeds (covermymeds): medication requests. HealOS reads the chart, drafts the answers to the plan’s questions, a clinician reviews them, and HealOS fills the CoverMyMeds form.
Availity (availity): procedure requests that an EHR workflow (eCW or ModMed) files in Availity.

The prior-auth endpoints let you follow those requests and the payer’s decision from your own system. Starting requests through the API is not available yet.

Endpoint	Scope	What it does
`GET /prior-auth/requests`	`prior_auth:read`	List requests from both tracks, newest change first
`GET /prior-auth/requests/{requestId}`	`prior_auth:read`	Get one request
`GET /prior-auth/requests/{requestId}/events`	`prior_auth:read`	What happened to a request
`GET /prior-auth/workflows`	`prior_auth:read`	Your EHR → portal workflows and their last run
`POST /prior-auth/status-checks`	`prior_auth:write`	Read Availity decisions now

A request names a drug or procedure, a payer and a diagnosis for one patient, so responses are protected health information. Only use these endpoints under your business associate agreement with HealOS. Chart data, drafted answers and portal screenshots are never returned.

Status and decision

Each request has two independent fields. status is where HealOS is in the work:

`status`	Meaning
`in_progress`	HealOS is preparing or filling the request
`needs_review`	A clinician must review the drafted answers in HealOS
`ready_for_person`	The portal form is filled and saved; a person sends it
`submitted`	Sent to the plan
`needs_attention` / `failed`	HealOS stopped; open the request in the dashboard

decision is the payer’s latest decision as the portal shows it: pending, approved, denied, cancelled or closed. It is null until the request reaches the plan. decision_checked_at says when HealOS last read it. HealOS reads CoverMyMeds decisions every hour and Availity decisions every day. raw_status is HealOS’s internal status. Use it when you contact support, not for logic.

List requests

curl "https://api.healos.ai/ext-api/v1/prior-auth/requests?decision=approved&limit=50" \
  -H "X-API-Key: $HEALOS_API_KEY"

{
  "data": [
    {
      "id": "5b0e3c1a-2f4d-4c1e-9a43-0d7e1b2c3a4f",
      "track": "availity",
      "status": "submitted",
      "raw_status": "submitted",
      "decision": "approved",
      "decision_checked_at": "2026-10-22T14:00:00.000Z",
      "payer": "UHC",
      "drug_name": null,
      "diagnosis_code": null,
      "portal_ref": "REF123",
      "authorization_id": "AUTH9",
      "effective_date": "2026-10-22",
      "expiration_date": "2027-01-22",
      "ehr_patient_id": null,
      "workflow_id": "0d6c…",
      "created_at": "2026-10-19T09:00:00.000Z",
      "updated_at": "2026-10-22T14:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total_pages": 1 }
}

Filters: track, status, decision and updated_since (ISO 8601). The list covers the 500 most recently changed requests per track. To stay in sync, store the time of your last sync and pass it as updated_since.

Events

GET /prior-auth/requests/{requestId}/events returns up to 100 events, newest first. Each has a type, a time at, and a decision on decision events. CoverMyMeds requests return HealOS’s event log, for example created, portal_draft_saved and portal_outcome_checked. Availity requests return started, finished and decision_changed.

Check decisions now

curl -X POST "https://api.healos.ai/ext-api/v1/prior-auth/status-checks" \
  -H "X-API-Key: $HEALOS_API_KEY"

This returns 202 and reads the decisions of your open Availity requests in the background, the same as Check status now in the dashboard. It takes a few minutes. Read the results from the requests list afterwards.

404: your organization has no Availity workflow.
409: decisions were checked in the last 10 minutes, or a workflow is filling a form right now. Try again later.

CoverMyMeds decisions are not part of this call. HealOS checks them every hour.

Getting Started

Resources

Prior Authorization

Prior Authorization

Status and decision

List requests

Events

Check decisions now

​Prior Authorization

​Status and decision

​List requests

​Events

​Check decisions now

Prior Authorization

Status and decision

List requests

Events

Check decisions now