# Check MA internal criteria (preview)

URL: https://docs.healthcare.dev/recipes/ma-internal-criteria

<Callout type="warn" title="Preview: not available yet">
  Medicare Advantage internal criteria are built but not released. Until they are, the endpoints
  answer `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          | [Medicare Advantage internal criteria](/datasets/ma-internal-criteria) (plans' public postings) |
| Calls per answer | 1, plus 1 to find the plan id                                                                   |

A Medicare Advantage plan has to follow Medicare's own coverage rules (NCDs and LCDs). Where those
don't fully establish the criteria for a service, the plan may use internal criteria of its own,
and must post them. This recipe tells you whether a plan's posting covers a code that way, and
where the plan's document is.

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

## 1. Find the plan

```sh
curl "https://api.healthcare.dev/v1/medicare-advantage/plans?q=humana" \
  -H "Authorization: Bearer $HDEV_API_KEY"
```

`plan_id` is a Medicare Advantage contract (`H1036`) or an organization id from this list. A
contract answers with its organization's posting, which applies to all its plans.

## 2. Ask about a code

```sh
curl "https://api.healthcare.dev/v1/medicare-advantage/H1036/criteria?code=91110" \
  -H "Authorization: Bearer $HDEV_API_KEY"
```

```json
{
  "data": {
    "plan": { "id": "H1036", "applies_to": "all_ma_plans", "...": "..." },
    "code": "91110",
    "disclaimer": "Reference data, not a coverage determination.",
    "pending_review": 0,
    "criteria": [
      {
        "service": { "key": "capsule-endoscopy", "policy_id": null, "name": "Capsule Endoscopy" },
        "codes": ["91110", "91111", "91112", "91299"],
        "uses_internal_criteria": {
          "answer": "yes",
          "confidence": 0.8,
          "derivation": "derived",
          "evidence": [{ "url": "https://..." }],
          "as_of": "2026-10-25T05:30:00.000Z"
        },
        "basis": "organization_statement",
        "criteria_url": "https://...",
        "posting_url": "https://...",
        "updated_date": "2026-09-01"
      }
    ]
  }
}
```

**TypeScript**

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

const hdev = new HealthcareDev();

const { data } = await hdev.medicareAdvantage.criteria("H1036", { code: "91110" });
for (const c of data.criteria) {
  const { answer, derivation, confidence } = c.uses_internal_criteria;
  console.log(c.service.name, answer, derivation, confidence, c.criteria_url);
}
console.log(data.disclaimer);
```

**Python**

```python
from healthcare_dev import HealthcareDev

hdev = HealthcareDev()

ma = hdev.medicare_advantage.criteria("H1036", code="91110")["data"]
for c in ma["criteria"]:
    u = c["uses_internal_criteria"]
    print(c["service"]["name"], u["answer"], u["derivation"], u["confidence"], c["criteria_url"])
print(ma["disclaimer"])
```

## Ask an agent

> Does Medicare Advantage contract H1036 use internal coverage criteria for code 91110? Link the
> plan's policy document, say how sure the answer is, and remind me this isn't a coverage
> determination.

The agent uses `check_ma_internal_criteria`.

## Read the answer

- **`uses_internal_criteria.answer`** is `yes` or `no`, as the plan's posting states it.
- **`derivation`**: `source_stated` (`confidence: 1`) when the organization says plainly that
  every policy it lists is written where Medicare's criteria aren't fully established; `derived`
  (`confidence` below 1) when it says it _may_ apply internal criteria in the policies it lists,
  without saying which, so the plan's document says where they apply; `reviewed` when a person
  read the posting. Policies waiting for that person aren't listed; `pending_review` counts them.
- **`criteria_url`** is the plan's own document: read it for the criteria. We never serve the
  criteria text.
- **`differs_from_medicare_criteria`** appears only when a person confirmed a difference from an
  NCD or LCD.
- **No service listing the code** means only that: the plan may cover it under a policy without
  a code list, or follow Medicare's own criteria. Check
  [Medicare coverage](/recipes/medicare-coverage) for those.

## What it is not

Reference data, not a coverage determination. Codes are served as numbers only, never with CPT
descriptions.