# Check a prior auth requirement (preview)

URL: https://docs.healthcare.dev/recipes/prior-auth-requirements

<Callout type="warn" title="Preview: not available yet">
  Prior authorization requirements are built but not released. Until they are, the endpoint answers
  `503` `dataset-unavailable`. This recipe shows how it will work; details may change before
  release.
</Callout>

|                  |                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| Plan             | **Pro** and up, or a preview on Free and Builder once released                                             |
| Dataset          | [Prior authorization requirements](/datasets/prior-auth) (payers' public lists)                            |
| Calls per answer | 1                                                                                                          |
| Limits           | A daily cap on different payer and code pairs per account (`429` `enumeration-limit`); repeats don't count |

<Callout title="Try it before you upgrade">
  Free and Builder keys can call it as a preview: 50 preview calls a month on Free, 200 on Builder,
  per feature. A preview answer is the real answer, with `meta.preview` (calls `remaining` this
  month and the plan that `unlocks` it) and `links.upgrade`. Preview calls count toward your
  included calls. Once they're used up, the `403` `plan-upgrade-required` adds `upgrade_url` and a
  sample answer for a fixed demo subject. See [Plans](/plans#previews).
</Callout>

## Ask for the requirement

`payer` is a payer id (`aetna`, `cigna`, `humana`, ...). `code` is a CPT number or HCPCS Level II
code. `line` (`commercial`, `medicare_advantage`, `medicaid`) limits it to one line of business;
without it you get every line the payer's lists cover. `modifier` matches lists that name one.

```sh
curl "https://api.healthcare.dev/v1/prior-auth?payer=cigna&code=27447&line=commercial" \
  -H "Authorization: Bearer $HDEV_API_KEY"
```

```json
{
  "data": {
    "payer": { "id": "cigna", "name": "Cigna Healthcare" },
    "code": "27447",
    "disclaimer": "Reference data, not a prior authorization determination. Confirm with the payer.",
    "requirements": [
      {
        "line": "commercial",
        "prior_auth": {
          "answer": "required",
          "confidence": 1,
          "derivation": "source_stated",
          "evidence": [{ "url": "https://www.cigna.com/...", "anchor": "page 31" }],
          "as_of": "2026-10-20T05:30:00.000Z"
        },
        "effective_start": "2020-01-01",
        "effective_end": null,
        "conditions": [],
        "upcoming": [],
        "conflicts": [],
        "note": null
      }
    ],
    "lines_available": ["commercial"]
  }
}
```

**TypeScript**

```ts
import { HealthcareDev } from "@healthcare.dev/sdk";

const hdev = new HealthcareDev();

const { data } = await hdev.priorAuth.check({ payer: "cigna", code: "27447" });
for (const r of data.requirements) {
  const { answer, derivation, confidence, evidence } = r.prior_auth;
  console.log(r.line, answer, derivation, confidence, evidence[0]?.url, r.conditions, r.upcoming);
}
console.log(data.disclaimer);
```

**Python**

```python
from healthcare_dev import HealthcareDev

hdev = HealthcareDev()

pa = hdev.prior_auth.check(payer="cigna", code="27447")["data"]
for r in pa["requirements"]:
    p = r["prior_auth"]
    print(r["line"], p["answer"], p["derivation"], p["confidence"], r["conditions"], r["upcoming"])
print(pa["disclaimer"])
```

## Ask an agent

> Does Cigna require prior authorization for CPT 27447 on its commercial plans? Give the
> effective dates, any conditions, how the answer was reached, and a link to Cigna's list. Tell me
> to confirm with Cigna.

The agent uses `check_prior_auth`.

## Read the answer

`prior_auth.answer`, per line of business:

- **`required`**: a list says prior authorization is required for the code (or a range that
  includes it), in effect today.
- **`not_required`**: a list says it isn't, for example the payer removed the code on
  `effective_start`.
- **`unclear`**: a list mentions the code in a way our rules can't read reliably, or two of the
  payer's documents disagree. `conflicts` shows both with their links; we never pick one.
- **`not_listed`**: none of the payer's lists we hold for this line names the code. **Not proof
  prior authorization isn't needed**: payers don't say their lists are complete.

How it was reached:

- **`derivation`**: `source_stated` (`confidence: 1`) when a list states it and our rules read
  it; `reviewed` when a person read the row; `derived` for `unclear` (`confidence: 0`) and
  `not_listed` (`confidence: 1`, or `0.5` while rows of those lists wait for a person and might
  name the service without its code).
- **`evidence`** links the payer's list and page; **`as_of`** is when that version of the list
  was first seen.
- A change the list announces for a later date is in **`upcoming`**, not in the answer.

## What it is not

Reference data, not a prior authorization determination: confirm with the payer before
scheduling. Codes are served as numbers only, never with descriptions, and dental codes are
never served.