# Care categories

URL: https://docs.healthcare.dev/care-categories

Code sets are organized for billing and statistics, not for people. Care categories group them
the way a patient or a care navigator would: **Knee replacement**, **Diabetes supplies**,
**Blood thinners**, **Physical therapy and rehabilitation**. Every ICD-10-CM diagnosis,
ICD-10-PCS procedure, HCPCS Level II code and FDA NDC drug product can carry one or more of them.

Care categories are on every plan, Free included.

## The categories

About 270 categories in a hierarchy of up to four levels: top-level groups such as
`bones-joints-and-muscles`, then narrower ones such as `joint-replacement` and
`knee-replacement`. Each has a stable `slug` you can store, a `name` to show, its `parent`, its
`path` from the top and its `children`.

```sh
curl "https://api.healthcare.dev/v1/care-categories?q=diabetes" \
  -H "Authorization: Bearer $HDEV_API_KEY"
```

`GET /v1/care-categories` lists them all (or those whose name has every word of `q`). It is free:
it doesn't count toward your calls.

`GET /v1/care-categories/{slug}` returns one category with how many active records each system
has in it or in any category below it:

```json
{
  "data": {
    "slug": "knee-replacement",
    "name": "Knee replacement",
    "parent": "joint-replacement",
    "path": ["bones-joints-and-muscles", "joint-replacement", "knee-replacement"],
    "children": [],
    "counts": { "icd10cm": 5, "icd10pcs": 154, "hcpcs": 0, "ndc": 0 }
  }
}
```

A count is `null` while that system has no published version, or its categories aren't built
for the version just published.

`GET /v1/care-categories/{slug}/codes?system=icd10pcs` lists the records, in code order, 25 per
page (up to 100 with `limit`; follow `links.next`, whose cursor only works for the same category
and system). It answers `503` in the short window before a new version's categories are built:

```ts
for await (const c of hdev.careCategories.iterateCodes("knee-replacement", { system: "icd10pcs" }))
  console.log(c.code, c.display, c.derivation, c.confidence);
```

## On code and drug records

Code records (lookups, searches, the batch, children, parents and hierarchies under
`/v1/codes/{system}`) and NDC lookups (`/v1/drugs/ndc/{ndc}`) carry the record's categories:

- `care_categories`: the slugs, in every view.
- `care_category_details`: each category with how it was assigned, in the full view (the
  default).

```json
"care_categories": ["type-2-diabetes"],
"care_category_details": [
  {
    "slug": "type-2-diabetes",
    "name": "Type 2 diabetes",
    "confidence": 0.95,
    "derivation": "source_stated",
    "evidence": [
      {
        "url": "https://www.cms.gov/medicare/coding-billing/icd-10-codes",
        "anchor": "ICD-10-CM category E11"
      }
    ],
    "as_of": "2026-10-01T00:00:00.000Z"
  }
]
```

An empty `care_categories` means no category could be assigned with confidence. We leave a record
uncategorized rather than guess. A lookup with `as_of` (the record as it was on a past date)
carries no categories: they are worked out for the published version only.

## Which answers are inferred: `derivation`

A care category is our label, not the source's, so every one says how we got there:

| `derivation`    | What it means                                                                                                                                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_stated` | The source classifies the record this way and the category restates it: the ICD-10-CM block "Diabetes mellitus", the ICD-10-PCS root operation "Replacement" of a knee joint, a HCPCS code range, the FDA pharmacologic class "Insulin Analog". |
| `derived`       | We inferred it: from words in the description, from a classification that usually but not always means this category, or from a record's other fields. Check it before relying on it.                                                           |
| `reviewed`      | A person checked it against the source.                                                                                                                                                                                                         |

`evidence` names the source and the part of its structure the answer rests on (`anchor`), so you
can check it. `confidence` runs from 0 to 1; we don't assign a category below 0.8.

## Freshness

Categories are worked out again with every release of the source: a new ICD-10 code set, a
quarterly HCPCS update, each day's NDC directory. `as_of` is when the source version the answer
rests on took effect.

Care categories are reference data for navigation and search. They are not clinical advice and
not a coverage or billing determination.