# Prior authorization requirement for a payer and code

URL: https://docs.healthcare.dev/reference/prior-authorization/prior-authorization-requirement-for-a-payer-and-code

```http
GET https://api.healthcare.dev/v1/prior-auth
```

Preview: not available yet (503 `dataset-unavailable` until it is released). Pro plan and up (below Pro: a few preview calls a month, then 403 `plan-upgrade-required`). Whether a payer's public prior authorization (precertification) lists require prior authorization for a procedure code (CPT number or HCPCS Level II), per line of business (`commercial`, `medicare_advantage`, `medicaid`; `line` for one): `required`, `not_required` (for example, the payer removed the code from its list), `unclear` (the list mentions the code in a way our rules can't read reliably, or two of the payer's documents disagree: both are shown in `conflicts`), or `not_listed` (none of the payer's lists we hold names the code, which is not proof prior authorization isn't needed). Each answer carries `confidence`, `derivation`, `evidence` (the list and page) and `as_of`, the effective and end dates the list gives, conditions in plain words, and changes the list announces for later dates. Codes are served as numbers only, never with descriptions. Each account can look up a limited number of different payer and code pairs a day; repeats and failed lookups don't count (429 `enumeration-limit` past it, until 00:00 UTC). Reference data, not a prior authorization determination. Confirm with the payer.

Requires an API key: `Authorization: Bearer hdev_live_...`. See [Authentication](/authentication).

## Query parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `payer` | string | yes | Payer id (`aetna`, `cigna`, `humana`, ...) | `cigna` |
| `code` | string | yes | CPT code number or HCPCS Level II code | `27447` |
| `line` | "commercial" \| "medicare_advantage" \| "medicaid" | no | One line of business (default: every line the payer's lists cover) | `commercial` |
| `modifier` | string | no | Billing modifier, for lists that name one | `RT` |
| `view` | "compact" \| "standard" \| "full" | no | How much of each record to return (default `full`). `compact`: `payer`, `code`, `modifier`, `disclaimer`, `requirements` (fewest tokens, for agents). `standard`: every field. `full`: every field. | `compact` |
| `fields` | string | no | Comma-separated fields to return instead of a view. Valid fields: `payer`, `code`, `modifier`, `disclaimer`, `requirements`, `lines_available`. | `payer,code,modifier` |

## Examples

**curl**

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

**TypeScript**

```ts
const res = await fetch("https://api.healthcare.dev/v1/prior-auth?payer=cigna&code=27447", {
  headers: { Authorization: `Bearer ${process.env.HDEV_API_KEY}` },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os
import requests

res = requests.get("https://api.healthcare.dev/v1/prior-auth?payer=cigna&code=27447", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()
```

## Response

The payer's requirement for the code, per line of business

```json
{
  "data": {
    "payer": {
      "id": "string",
      "name": "string"
    },
    "code": "string",
    "modifier": "string",
    "disclaimer": "Reference data, not a prior authorization determination. Confirm with the payer.",
    "requirements": [
      {
        "line": null,
        "prior_auth": {
          "answer": null,
          "confidence": null,
          "derivation": null,
          "evidence": null,
          "as_of": null
        },
        "codes": [
          null
        ],
        "modifier": "string",
        "effective_start": "2026-10-01",
        "effective_end": "2026-10-01",
        "conditions": [
          null
        ],
        "upcoming": [
          null
        ],
        "conflicts": [
          null
        ],
        "note": "string"
      }
    ],
    "lines_available": [
      "commercial"
    ]
  },
  "meta": {
    "source": "cms-icd10",
    "data_version": "2026.1",
    "retrieved_at": "2026-10-24T12:00:00Z",
    "license": "Public domain (CMS). Reference data, not medical advice."
  },
  "links": {
    "self": "/v1/prior-auth?payer=cigna&code=27447",
    "next": null
  }
}
```

### Fields

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `payer` | object | yes |  |
| `code` | string | yes | The code asked about, upper case |
| `modifier` | string \| null | yes | The modifier asked about, if any |
| `disclaimer` | "Reference data, not a prior authorization determination. Confirm with the payer." | yes |  |
| `requirements` | PriorAuthRequirement[] | yes | One per line of business (only `line` when given), in a fixed order |
| `lines_available` | PriorAuthLine[] | yes | Lines of business we hold this payer's lists for |

## Errors

Errors are `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). Branch on `type`, not on `title`. See [Errors](/errors).

| Status | `type` | When |
| --- | --- | --- |
| 400 | `invalid-request` | A parameter or the body failed validation; `errors` lists each field. |
| 401 | `unauthorized` | Missing, malformed or revoked API key. |
| 403 | `plan-upgrade-required` | The plan doesn't include this feature; `required_plan` names the plan that does. |
| 404 | `not-found` | No record with that id (retired records are still returned). |
| 429 | `rate-limited / quota-exceeded` | Too many requests per second (retry after `Retry-After`), or the monthly quota is used up. |
| 503 | `dataset-unavailable / unavailable` | The dataset has no published version yet, or the service is degraded. |