> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prior Authorization

> Track prior-auth requests HealOS prepares and the payer's decision

# 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 |

> [!WARNING]
>
> 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

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

```json theme={null}
{
  "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

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.