ICD-10 API

Look up ICD-10-CM diagnosis codes and ICD-10-PCS procedure codes.

Overview

ICD-10 is the international standard for classifying diseases (ICD-10-CM) and procedures (ICD-10-PCS). FHIRfly automatically detects the code type and returns the appropriate data.

Endpoints

Method	Path	Description
GET	`/v1/icd10/:code`	Single code lookup
POST	`/v1/icd10/_batch`	Batch lookup (up to 100)
GET	`/v1/icd10/shapes`	List available response shapes

Single Lookup - Diagnosis (ICD-10-CM)

Look up Type 2 diabetes mellitus

Request

Node.js

import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

const result = await client.icd10.lookup("E11.9");
console.log(result.data);

Response

JSON

{
  "data": {
    "code": "E119",
    "code_system": "ICD-10-CM",
    "display": "Type 2 diabetes mellitus without complications",
    "fhir_coding": {
      "code": "E119",
      "display": "Type 2 diabetes mellitus without complications",
      "system": "http://hl7.org/fhir/sid/icd-10-cm"
    },
    "fiscal_year": "2026",
    "status": "ACTIVE",
    "structure": {
      "billable": true,
      "block": {
        "range": "E08-E13",
        "title": "Diabetes mellitus (E08-E13)"
      },
      "category": {
        "code": "E11",
        "title": "Type 2 diabetes mellitus"
      },
      "chapter": {
        "code": "4",
        "title": "Endocrine, nutritional and metabolic diseases (E00-E89)"
      },
      "kind": "diagnosis",
      "parent_code": "E11",
      "poa_exempt": false,
      "subcategory": "E119"
    },
    "system": "http://hl7.org/fhir/sid/icd-10-cm"
  },
  "meta": {
    "legal": {
      "attribution_required": false,
      "citation": "ICD-10-CM, CMS. Accessed 2026-01-14 via FHIRfly API.",
      "license": "public_domain",
      "source_name": "CMS ICD-10-CM"
    }
  }
}

Code Types

Type	Format	Example	Description
CM	A00-Z99 pattern	E11.9	Diagnosis codes
PCS	7 characters	0BH17EZ	Procedure codes

FHIRfly automatically detects the code type based on format. CM codes accept both dotted (E11.9) and non-dotted (E119) formats.

Batch Lookup

Look up multiple ICD-10 codes in a single request (up to 100). Supports mixed CM and PCS codes:

Look up multiple diagnosis codes

Request

Node.js

import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

const result = await client.icd10.lookupMany(["E11.9","I10","J06.9"]);
console.log(result.data.results);

Response

JSON

{
  "count": 3,
  "results": [
    {
      "input": "E11.9",
      "code": "E11.9",
      "status": "ok",
      "data": {
        "code_system": "ICD-10-CM",
        "display": "Type 2 diabetes mellitus without complications",
        "billable": true
      }
    },
    {
      "input": "I10",
      "code": "I10",
      "status": "ok",
      "data": {
        "code_system": "ICD-10-CM",
        "display": "Essential (primary) hypertension",
        "billable": true
      }
    },
    {
      "input": "J06.9",
      "code": "J06.9",
      "status": "ok",
      "data": {
        "code_system": "ICD-10-CM",
        "display": "Acute upper respiratory infection, unspecified",
        "billable": true
      }
    }
  ],
  "meta": {
    "legal": {
      "license": "public_domain"
    }
  }
}

Batch with `shape=full`

When using shape=full on batch requests, the response includes meta.source with provenance information:

POST /v1/icd10/_batch?shape=full

{
  "count": 3,
  "results": [
    {
      "input": "E11.9",
      "code": "E11.9",
      "status": "ok",
      "data": {
        "code_system": "ICD-10-CM",
        "display": "Type 2 diabetes mellitus without complications",
        "billable": true
      }
    }
  ],
  "meta": {
    "source": {
      "name": "CMS ICD-10-CM",
      "url": "https://www.cms.gov/medicare/coding-billing/icd-10-codes",
      "version": "FY2026",
      "fhirfly_updated_at": "2026-03-01T03:00:00Z"
    },
    "legal": {
      "license": "public_domain",
      "attribution_required": false
    }
  }
}

Response Shapes

Control the level of detail in responses with the shape query parameter:

Shape	Description
`compact`	Code, code_system, display, billable/short_desc
`standard`	+ status, fiscal_year, structure, fhir_coding
`full`	+ version, metadata, ingest info

# Minimal data
GET /v1/icd10/E11.9?shape=compact

# Standard data (default)
GET /v1/icd10/E11.9?shape=standard

# Full data with provenance
GET /v1/icd10/E11.9?shape=full

See Response Shapes for field details.

SNOMED CT Enrichment

ICD-10-CM codes with SNOMED mappings include a snomed array in standard and full shapes. This provides cross-terminology navigation between diagnosis codes and clinical concepts.

{
  "data": {
    "code": "E119",
    "display": "Type 2 diabetes mellitus without complications",
    "snomed": [
      {
        "concept_id": "44054006",
        "display": "Diabetes mellitus type 2",
        "map_type": "equivalent",
        "map_source": "snomed-extended-map"
      }
    ]
  }
}

The snomed field is only present on ICD-10-CM codes (not PCS). See SNOMED CT API for more details.

Required Scopes

icd10.read - Single and batch lookups