api reference

REST API Reference

Last updated: Jan 20, 2025

The FindICD10 API provides programmatic access to ICD-10-CM diagnosis codes, code conversion, and AI-powered clinical note analysis.

Base URL: https://findicd10.com/api

Authentication

No authentication required. The API is free to use with rate limiting.

Rate Limits

Client Type	Limit	Detection
Browser	120 requests/min	User-Agent contains browser identifier
API/Script	30 requests/min	Non-browser User-Agent

Rate limit headers are included in all responses:

text

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1705789200
X-RateLimit-Tier: api

When rate limited, you'll receive a 429 Too Many Requests response:

json

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Limit: 30/min",
  "retry_after": 45
}

Endpoints

Search Codes

Search across all ICD-10-CM diagnosis codes using full-text search.

text

GET /api/search

Parameters

Parameter	Type	Required	Default	Description
`q`	string	Yes	-	Search query (e.g., "diabetes", "chest pain")
`billable_only`	boolean	No	false	Only return billable (valid for submission) codes
`limit`	integer	No	50	Max results (1-100)
`version`	string	No	"2026"	ICD-10 version ("2025" or "2026")
`type`	string	No	"code"	Search type: "code", "drug", "neoplasm", or "all"

Response (default type="code")

json

[
  {
    "code": "E11.65",
    "name": "Type 2 diabetes mellitus with hyperglycemia",
    "description": "Type 2 diabetes mellitus with hyperglycemia",
    "is_billable": true,
    "path": "/E00-E89/E08-E13/E11/E11.6/E11.65"
  },
  {
    "code": "E11.9",
    "name": "Type 2 diabetes mellitus without complications",
    "description": "Type 2 diabetes mellitus without complications",
    "is_billable": true,
    "path": "/E00-E89/E08-E13/E11/E11.9"
  }
]

Response (type="all" unified search)

json

{
  "type": "all",
  "results": [
    {
      "type": "code",
      "code": "E11.65",
      "name": "Type 2 diabetes mellitus with hyperglycemia",
      "description": "...",
      "is_billable": true,
      "path": "/E00-E89/E08-E13/E11/E11.6/E11.65"
    },
    {
      "type": "drug",
      "id": "drug_123",
      "term": "Metformin",
      "level": 0,
      "codes": {
        "accidental": "T38.3X1A",
        "intentional": "T38.3X2A",
        "assault": "T38.3X3A",
        "undetermined": "T38.3X4A",
        "adverse_effect": "T38.3X5A",
        "underdosing": "T38.3X6A"
      }
    }
  ],
  "query": "diabetes",
  "version": "2026"
}

Example

bash

curl "https://findicd10.com/api/search?q=diabetes&billable_only=true&limit=10"

Get Code Details

Retrieve detailed information about a specific ICD-10-CM code.

text

GET /api/codes/{code}

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	ICD-10-CM code (e.g., "E11.65", "A00.0")

Response

json

{
  "code": "E11.65",
  "description": "Type 2 diabetes mellitus with hyperglycemia",
  "isBillable": true,
  "type": "CODE",
  "details": {
    "notes": [],
    "codeFirst": [],
    "codeAlso": [],
    "useAdditionalCode": [
      "Use additional code to identify control using:",
      "insulin (Z79.4)",
      "oral antidiabetic drugs (Z79.84)",
      "oral hypoglycemic drugs (Z79.84)"
    ],
    "excludes1": [
      "diabetes mellitus due to underlying condition (E08.-)",
      "drug or chemical induced diabetes mellitus (E09.-)",
      "gestational diabetes (O24.4-)",
      "neonatal diabetes mellitus (P70.2)",
      "type 1 diabetes mellitus (E10.-)"
    ],
    "excludes2": [],
    "inclusionTerms": [],
    "sevenCharNote": null,
    "sevenCharDefs": []
  },
  "children": []
}

Response Fields

Field	Type	Description
`code`	string	The ICD-10 code
`description`	string	Full description of the code
`isBillable`	boolean	Whether this code can be used for billing
`type`	string	Node type: "CHAPTER", "SECTION", "CATEGORY", or "CODE"
`details.notes`	string[]	General clinical notes
`details.codeFirst`	string[]	Conditions to code before this one
`details.codeAlso`	string[]	Additional codes to consider
`details.useAdditionalCode`	string[]	Codes to add for more specificity
`details.excludes1`	string[]	Codes that CANNOT be used together
`details.excludes2`	string[]	Codes "not included here" but CAN be used together
`details.inclusionTerms`	string[]	Conditions included in this code
`details.sevenCharNote`	string	Instructions for 7th character
`details.sevenCharDefs`	object[]	7th character definitions
`children`	object[]	Child codes in the hierarchy

Example

bash

curl "https://findicd10.com/api/codes/E11.65"

Get Related Codes

Retrieve sibling codes (codes at the same level in the hierarchy).

text

GET /api/codes/{code}/siblings

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	ICD-10-CM code

Response

json

{
  "siblings": [
    {
      "code": "E11.61",
      "name": "Type 2 diabetes mellitus with diabetic arthropathy",
      "description": "Type 2 diabetes mellitus with diabetic arthropathy",
      "is_billable": false,
      "node_type": "category"
    },
    {
      "code": "E11.62",
      "name": "Type 2 diabetes mellitus with skin complications",
      "description": "Type 2 diabetes mellitus with skin complications",
      "is_billable": false,
      "node_type": "category"
    },
    {
      "code": "E11.65",
      "name": "Type 2 diabetes mellitus with hyperglycemia",
      "description": "Type 2 diabetes mellitus with hyperglycemia",
      "is_billable": true,
      "node_type": "code"
    }
  ]
}

Example

bash

curl "https://findicd10.com/api/codes/E11.65/siblings"

Convert ICD-9 to ICD-10

Convert between ICD-9-CM and ICD-10-CM codes using official CMS GEM (General Equivalence Mappings).

text

GET /api/convert

Parameters

Parameter	Type	Required	Default	Description
`code`	string	Yes	-	ICD-9 or ICD-10 code to convert
`version`	string	No	"2026"	ICD-10 version for mapping

The API automatically detects whether you're providing an ICD-9 or ICD-10 code:
- ICD-9: Starts with 0-9, V, or E (e.g., "250.00", "V58.11")
- ICD-10: Starts with A-T or Z (e.g., "E11.65", "Z79.4")

Response

json

{
  "inputCode": "250.00",
  "inputType": "icd9",
  "mappings": [
    {
      "icd9_code": "25000",
      "icd10_code": "E119",
      "direction": "forward",
      "approximate": true,
      "no_map": false,
      "combination": false
    }
  ]
}

Response Fields

Field	Type	Description
`inputCode`	string	The code you submitted
`inputType`	string	"icd9" or "icd10"
`mappings[].icd9_code`	string	ICD-9 code (without decimal)
`mappings[].icd10_code`	string	ICD-10 code (without decimal)
`mappings[].direction`	string	"forward" (ICD-9->10) or "backward" (ICD-10->9)
`mappings[].approximate`	boolean	True if mapping is not exact
`mappings[].no_map`	boolean	True if no direct mapping exists
`mappings[].combination`	boolean	True if multiple codes needed

Example

bash

# ICD-9 to ICD-10
curl "https://findicd10.com/api/convert?code=250.00"

# ICD-10 to ICD-9
curl "https://findicd10.com/api/convert?code=E11.65"

Analyze Clinical Note

Extract ICD-10 codes from clinical text using AI analysis.

text

POST /api/analyze

Request Body

json

{
  "note": "Patient is a 45-year-old male with uncontrolled type 2 diabetes mellitus, diabetic peripheral neuropathy, and stage 3 chronic kidney disease. Blood glucose 285."
}

Response

json

{
  "codes": [
    {
      "Code": "E11.65",
      "Rationale": "Uncontrolled type 2 diabetes with elevated blood glucose (285) indicates hyperglycemia",
      "Confidence": 5,
      "Description": "Type 2 diabetes mellitus with hyperglycemia",
      "Billable": true
    },
    {
      "Code": "E11.42",
      "Rationale": "Diabetic peripheral neuropathy documented",
      "Confidence": 5,
      "Description": "Type 2 diabetes mellitus with diabetic polyneuropathy",
      "Billable": true
    },
    {
      "Code": "E11.22",
      "Rationale": "Chronic kidney disease with documented diabetes indicates diabetic CKD",
      "Confidence": 4,
      "Description": "Type 2 diabetes mellitus with diabetic chronic kidney disease",
      "Billable": true
    },
    {
      "Code": "N18.3",
      "Rationale": "Stage 3 chronic kidney disease explicitly documented",
      "Confidence": 5,
      "Description": "Chronic kidney disease, stage 3 (moderate)",
      "Billable": true
    }
  ]
}

Response Fields

Field	Type	Description
`codes[].Code`	string	ICD-10-CM code
`codes[].Rationale`	string	AI explanation for selecting this code
`codes[].Confidence`	number	Confidence level (0-5)
`codes[].Description`	string	Code description from database
`codes[].Billable`	boolean	Whether code is billable

Example

bash

curl -X POST "https://findicd10.com/api/analyze" \
  -H "Content-Type: application/json" \
  -d '{"note": "Patient with type 2 diabetes and foot ulcer on left heel"}'

ICD-10-PCS Endpoints

Get PCS Sections

List all 17 ICD-10-PCS sections.

text

GET /api/pcs/sections

Response

json

{
  "sections": [
    { "id": "0", "name": "Medical and Surgical" },
    { "id": "1", "name": "Obstetrics" },
    { "id": "2", "name": "Placement" },
    { "id": "3", "name": "Administration" }
  ]
}

Get Body Systems

List body systems within a PCS section.

text

GET /api/pcs/{section}

Response

json

{
  "section": {
    "id": "0",
    "name": "Medical and Surgical"
  },
  "bodySystems": [
    { "code": "0", "name": "Central Nervous System and Cranial Nerves" },
    { "code": "1", "name": "Peripheral Nervous System" },
    { "code": "2", "name": "Heart and Great Vessels" }
  ]
}

Get PCS Table

Get the full PCS code-building table with all axes and labels.

text

GET /api/pcs/{section}/{bodySystem}/{operation}

Response

json

{
  "section": { "id": "0", "name": "Medical and Surgical" },
  "bodySystem": { "code": "2", "name": "Heart and Great Vessels" },
  "operation": {
    "code": "1",
    "name": "Bypass",
    "definition": "Altering the route of passage of the contents of a tubular body part"
  },
  "table": {
    "id": "021",
    "axes": [
      {
        "position": 4,
        "title": "Body Part",
        "labels": [
          { "code": "0", "description": "Coronary Artery, One Artery" },
          { "code": "1", "description": "Coronary Artery, Two Arteries" }
        ]
      },
      {
        "position": 5,
        "title": "Approach",
        "labels": [
          { "code": "0", "description": "Open" },
          { "code": "3", "description": "Percutaneous" }
        ]
      }
    ]
  }
}

Error Responses

All endpoints return consistent error responses:

json

{
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

Code	Description
200	Success
400	Bad request (missing or invalid parameters)
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Caching

All responses include cache headers for optimal performance:

text

Cache-Control: public, s-maxage=3600, stale-while-revalidate=7200

s-maxage=3600: CDN caches for 1 hour
stale-while-revalidate=7200: Serve stale content while revalidating for up to 2 hours

Support

Issues: Contact us
Data Source: Official CMS ICD-10-CM files
Updates: Code database updated annually (October)