ICD-10-CM Tree

Status: stable Category: lookup Added: 2026-10-14 Last reviewed: 2026-10-14

Summary

Returns one level of the ICD-10-CM hierarchy: a node, its ancestors, and its direct children, each child flagged with has_children. Call it without node to get the 22 chapters, then pass any child's code back as node to drill down — chapter, section, category, subcategory, code. Built for a drill-down browser that fires on every expand.

The tree carries labels only, never coding notes. Fetch a node's notes with /api/lookup/icd10cm/get.

Endpoint

Field	Value
Method	GET
Path	/api/lookup/icd10cm/tree
Full URL	https://engine.tripod-health.com/api/lookup/icd10cm/tree
Authentication	API key (required)
Request body	none
Response body	application/json
Idempotent	Yes
Rate-limited	Yes

Authentication

Send a valid API key in the apikey header. See authentication.md.

Request

Headers

Header	Required	Description
apikey	Yes	Consumer API key.

Path parameters

None.

Query parameters

Parameter	Type	Required	Default	Description
node	string	No	—	The node to expand: a chapter number (1–22), a section range (S60-S69), or a code with or without the dot (S62, S62.001, s62001). Omit it to get the chapters.

Body

None.

Response

Success — 200 OK

Request: GET /api/lookup/icd10cm/tree?node=S62.001

S62.001 is a stem that requires a 7th character, so its children are exactly the complete, billable codes the release defines for it.

{
  "node": {
    "code": "S62.001",
    "label": "Unspecified fracture of navicular [scaphoid] bone of right wrist",
    "kind": "subcategory",
    "billable": false
  },
  "ancestors": [
    {
      "code": "19",
      "label": "Injury, poisoning and certain other consequences of external causes",
      "kind": "chapter",
      "billable": false
    },
    {
      "code": "S60-S69",
      "label": "Injuries to the wrist, hand and fingers",
      "kind": "section",
      "billable": false
    },
    {
      "code": "S62",
      "label": "Fracture at wrist and hand level",
      "kind": "category",
      "billable": false
    },
    {
      "code": "S62.0",
      "label": "Fracture of navicular [scaphoid] bone of wrist",
      "kind": "subcategory",
      "billable": false
    },
    {
      "code": "S62.00",
      "label": "Unspecified fracture of navicular [scaphoid] bone of wrist",
      "kind": "subcategory",
      "billable": false
    }
  ],
  "children": [
    {
      "code": "S62.001A",
      "label": "Unspecified fracture of navicular [scaphoid] bone of right wrist, initial encounter for closed fracture",
      "kind": "code",
      "billable": true,
      "has_children": false
    },
    {
      "code": "S62.001B",
      "label": "Unspecified fracture of navicular [scaphoid] bone of right wrist, initial encounter for open fracture",
      "kind": "code",
      "billable": true,
      "has_children": false
    },
    {
      "code": "S62.001D",
      "label": "Unspecified fracture of navicular [scaphoid] bone of right wrist, subsequent encounter for fracture with routine healing",
      "kind": "code",
      "billable": true,
      "has_children": false
    },
    {
      "code": "S62.001G",
      "label": "Unspecified fracture of navicular [scaphoid] bone of right wrist, subsequent encounter for fracture with delayed healing",
      "kind": "code",
      "billable": true,
      "has_children": false
    },
    {
      "code": "S62.001K",
      "label": "Unspecified fracture of navicular [scaphoid] bone of right wrist, subsequent encounter for fracture with nonunion",
      "kind": "code",
      "billable": true,
      "has_children": false
    },
    {
      "code": "S62.001P",
      "label": "Unspecified fracture of navicular [scaphoid] bone of right wrist, subsequent encounter for fracture with malunion",
      "kind": "code",
      "billable": true,
      "has_children": false
    },
    {
      "code": "S62.001S",
      "label": "Unspecified fracture of navicular [scaphoid] bone of right wrist, sequela",
      "kind": "code",
      "billable": true,
      "has_children": false
    }
  ],
  "release": "FY2027",
  "request_id": "c68f0eb3-c3c2-4a8b-aa09-ba4b283fb78b",
  "timestamp": "2026-10-14T00:15:10.227Z"
}

Without node, node is null, ancestors is empty, and children holds the 22 chapters:

{
  "node": null,
  "ancestors": [],
  "children": [
    { "code": "1", "label": "Certain infectious and parasitic diseases", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "2", "label": "Neoplasms", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "3", "label": "Diseases of the blood and blood-forming organs and certain disorders involving the immune mechanism", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "4", "label": "Endocrine, nutritional and metabolic diseases", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "5", "label": "Mental, Behavioral and Neurodevelopmental disorders", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "6", "label": "Diseases of the nervous system", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "7", "label": "Diseases of the eye and adnexa", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "8", "label": "Diseases of the ear and mastoid process", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "9", "label": "Diseases of the circulatory system", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "10", "label": "Diseases of the respiratory system", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "11", "label": "Diseases of the digestive system", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "12", "label": "Diseases of the skin and subcutaneous tissue", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "13", "label": "Diseases of the musculoskeletal system and connective tissue", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "14", "label": "Diseases of the genitourinary system", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "15", "label": "Pregnancy, childbirth and the puerperium", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "16", "label": "Certain conditions originating in the perinatal period", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "17", "label": "Congenital malformations, deformations, chromosomal abnormalities, and genetic disorders", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "18", "label": "Symptoms, signs and abnormal clinical and laboratory findings, not elsewhere classified", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "19", "label": "Injury, poisoning and certain other consequences of external causes", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "20", "label": "External causes of morbidity", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "21", "label": "Factors influencing health status and contact with health services", "kind": "chapter", "billable": false, "has_children": true },
    { "code": "22", "label": "Codes for special purposes", "kind": "chapter", "billable": false, "has_children": true }
  ],
  "release": "FY2027",
  "request_id": "88b0e963-dd68-4dff-8c9f-5597bb02963b",
  "timestamp": "2026-10-14T00:15:39.194Z"
}

Response fields

Field	Type	Always present	Description
node	object | null	Yes	The expanded node as { code, label, kind, billable }. null when node was omitted.
ancestors	array	Yes	The node's ancestors, root (chapter) first, each { code, label, kind, billable }. Empty at the top level and for a chapter.
children	array	Yes	The node's direct children, in tabular order. Empty for a leaf code.
children[].code	string	Yes	The child's key. Pass it back as node to expand it, or as code to get.
children[].label	string	Yes	The child's official description.
children[].kind	string	Yes	chapter, section, category, subcategory, or code.
children[].billable	boolean	Yes	true when the child is valid on a claim.
children[].has_children	boolean	Yes	true when expanding the child returns further children. Use it to draw the expand control.
release	string | null	Yes	The ICD-10-CM release the tree reflects, e.g. FY2027.
request_id	string	Yes	Correlation ID. Quote in support tickets.
timestamp	string (ISO 8601 UTC)	Yes	Server time when the response was emitted.

Status codes

Code	Meaning	When
200	OK	Level returned.
400	ValidationError	node is malformed, a chapter number outside 1–22, in incomplete-code notation (S62.-), or repeated. field is node.
401	Unauthenticated	Missing or invalid API key.
404	NotFound	node is well-formed but no such node exists in the release.
429	RateLimited	Per-consumer rate limit exceeded.
500	InternalError	Unexpected failure. Quote request_id in the ticket.

Examples

curl

curl -sS "https://engine.tripod-health.com/api/lookup/icd10cm/tree?node=S62.001" \
  -H "apikey: $ENGINE_API_KEY"

Python (requests)

# Uses the call() helper from quickstart.md.
level = call("GET", "/api/lookup/icd10cm/tree?node=S60-S69")
print(" > ".join(a["label"] for a in level["ancestors"] + [level["node"]]))
for child in level["children"]:
    marker = "+" if child["has_children"] else " "
    print(f"{marker} {child['code']:8}  {child['label']}")

Node.js (native fetch)

// Uses the call() helper from quickstart.md.
const chapters = await call("GET", "/api/lookup/icd10cm/tree");
const injury = chapters.children.find((c) => c.code === "19");
const sections = await call("GET", `/api/lookup/icd10cm/tree?node=${injury.code}`);
console.log(sections.children.map((s) => `${s.code} ${s.label}`).join("\n"));

TypeScript

type Icd10cmKind = "chapter" | "section" | "category" | "subcategory" | "code";

interface Icd10cmNode {
  code: string;
  label: string;
  kind: Icd10cmKind;
  billable: boolean;
}

interface Icd10cmTreeResponse {
  node: Icd10cmNode | null;
  ancestors: Icd10cmNode[];
  children: (Icd10cmNode & { has_children: boolean })[];
  release: string | null;
  request_id: string;
  timestamp: string;
}

const level = await call<Icd10cmTreeResponse>("GET", "/api/lookup/icd10cm/tree?node=S62");

Error scenarios

Chapter number out of range

Send:

curl -sS "https://engine.tripod-health.com/api/lookup/icd10cm/tree?node=23" \
  -H "apikey: $ENGINE_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Receive (400):

{
  "timestamp": "2026-10-14T00:15:38.509Z",
  "error": "ValidationError",
  "message": "'node' chapter numbers run from 1 to 22",
  "field": "node",
  "request_id": "52f39400-55bf-404d-abfa-9ca266b7fe6b"
}

Unknown node

Send:

curl -sS "https://engine.tripod-health.com/api/lookup/icd10cm/tree?node=S62.95" \
  -H "apikey: $ENGINE_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Receive (404):

{
  "timestamp": "2026-10-14T00:15:57.262Z",
  "error": "NotFound",
  "message": "No ICD-10-CM node 'S62.95'",
  "request_id": "dcfda7c1-e1d6-4cd7-bdbc-273b04ae7b1e"
}

Intended use

• Drill-down browsers that expand one node at a time — the response is always exactly one level, and has_children tells you which children can be expanded further.
• Listing a code family. ?node=S62 returns the subcategories under a category — the supported alternative to S62.- notation.
• Offering 7th-character choices. Expanding a stem that requires a 7th character returns exactly its valid complete codes.
• Breadcrumbs. ancestors is the path from the chapter to the node, ready to render.

Mistaken use

• Do not use the tree to find codes by words. It matches nothing — it returns structure. Use /api/lookup/icd10cm/search.
• Do not expect coding notes. The tree is labels only. Fetch notes with /api/lookup/icd10cm/get.
• Do not walk the whole code set level by level to build a local copy. Expand nodes as a user opens them; search answers "find me a code" in one call.

Debugging

1. Capture request_id. Present in every response body.
2. 400 ValidationError naming node. Chapters are numbered 1 to 22; sections are ranges such as S60-S69; anything else must be code-shaped.
3. 404 NotFound for a code-shaped node. The release contains no node with that key. Expand its parent to see which children exist.
4. Empty children. The node is a leaf (a complete code). Its has_children was false in the parent's listing.

Rate limits

See rate-limits.md for the current per-consumer limits.

Related

• lookup-icd10cm-search.md — find codes by words or a code fragment.
• lookup-icd10cm-get.md — one node's full record with coding notes.
• lookup-cpt-tree.md — the same tree shape for procedure codes.
• lookup-regulations-tree.md — the regulations structure browser.
• authentication.md, errors.md, rate-limits.md, conventions.md — cross-cutting contract rules.

Change history

Date	Change
2026-10-14	Initial publication.
2026-10-14	The engine assigns every request ID; an X-Request-ID request header is not used.