The ICD10 Rules API is in private preview. Contact us to arrange access for your software.

Request access

API reference

Validate ICD-10-CM diagnosis codes against published coding rules, retrieve any code with its notes, and search or browse the code set through a simple JSON API.

A first request
curl https://api.icd10rules.com/v1/check \
  -H "Content-Type: application/json" \
  -d '{"codes": ["E10.9", "E11.9"]}'

Introduction

The ICD10 Rules API validates ICD-10-CM diagnosis codes against published coding rules and returns reference data for any code. It follows REST conventions: requests and responses are JSON, and standard HTTP status codes indicate the outcome of each request.

EndpointPurpose
POST /checkValidate 2 to 10 diagnosis codes against the coding rules
GET /codes/{code}Retrieve a code with its description and notes
GET /searchSearch by code, range or description
GET /browseList the codes in a chapter or block
GET /releasesList the available code sets
GET /healthReport service status

Codes are accepted with or without the decimal point (E11.9 or E119) and are always returned with it. The API accepts diagnosis codes and, optionally, a patient age. It neither requires nor accepts information that identifies a patient.

Base URL
https://api.icd10rules.com/v1

Access and limits

The API is in private preview. Access for your own software is arranged individually: contact contact@icd10rules.com to discuss your use case and expected volume.

Requests are rate limited per client. Each response includes a RateLimit-Policy header identifying the limit that applies, for example 10;w=60 (10 requests per 60 seconds). The default limits are:

EndpointDefault limit
POST /check10 per minute, 30 per day
GET /codes/{code}; GET /search by code, prefix or range60 per minute, 300 per day
GET /search by description; GET /browse20 per minute, 100 per day

Daily limits reset at 00:00 UTC. Only successful requests that read data count toward a limit; rejected requests and cached responses do not. A request that exceeds a limit returns 429 with the error code rate_limited (per minute) or daily_limit_reached (per day) and a Retry-After header in seconds.

Call the API from your server. Cross-origin requests from browsers are accepted only from icd10rules.com.

Code sets

Each ICD-10-CM release is available as a code set, listed by GET /releases. Every endpoint except /releases and /health answers from a single code set and identifies it in the release field of the response.

To select a code set, send either release (an id from /releases) or date_of_service (YYYY-MM-DD), but not both. If neither is sent, the current code set is used. A date of service is resolved to the code set in effect on that date:

releaseCode setEffective
2027.0FY20272026-10-01 to 2027-09-30
2026.1FY2026 April update2026-04-01 to 2026-09-30
2026.0FY20262025-10-01 to 2026-03-31

A date of service earlier than 2025-10-01 returns 404. For POST /check, send release or date_of_service in the request body; for all other endpoints, send it as a query parameter.

A date of service
GET /v1/codes/E11.9?date_of_service=2026-05-01
Response (abridged)
{
  "release": "2026.1",
  "code": "E11.9",
  "description": "Type 2 diabetes mellitus without complications"
}

Rules

Use rules to select the rules to run, or omit it to run all of them. valid_code always runs, and age runs only when patient.age is provided. The checked field of the response lists the rules that were run.

RuleFlags
valid_codeA code that is not in the code set, or a header code that is not billable. Where a placeholder X is missing, the completed code is suggested.
excludes1Two codes that an Excludes1 note indicates are not normally reported together.
code_firstA code listed before the underlying condition that its Code First note requires to be sequenced first.
seventh_charA code that requires a 7th character, or a 7th character that is not valid for the code.
ageA code whose age range does not include the patient age provided.
manifestationA manifestation code listed first, or listed with no preceding underlying condition named by its Code First note.
principalA first-listed code that CMS does not accept in that position: an external cause code or an unacceptable principal diagnosis.
lateralityAn unspecified-side code where side-specific codes exist, or right and left codes where a bilateral code exists.
Excludes1 only
POST /v1/check
Body
{
  "codes": [
    "E10.9",
    "E11.9",
    "I10"
  ],
  "rules": [
    "excludes1"
  ]
}
Response (abridged)
{
  "status": "review",
  "release": "2027.0",
  "checked": [
    "valid_code",
    "excludes1"
  ]
}

Findings

A check returns status clear when no rule flagged the codes and review when at least one did. Each flagged item is returned in findings.

Each finding has a severity. error indicates a definite problem: an invalid code, a non-billable header code or a missing 7th character. review indicates an item that requires a coder's judgment.

Excludes1 findings always have severity review. The ICD-10-CM Official Guidelines (Section I.A.12.a) permit both codes to be reported when the two conditions are unrelated. The API therefore identifies the pair and every applicable note, with the code that carries each note, and leaves the determination to the coder.

  • codes: the codes the finding concerns, in claim order. For Excludes1, the pair; for Code First, the code carrying the note followed by the condition listed after it.
  • message: a one-sentence description suitable for display to the coder.
  • notes: Excludes1 only. Each note as published, with its carrier (a code, block or chapter).
  • note and carrier: Code First only. The note as published and the code that carries it.
  • options: the valid 7th characters, each with its meaning.
  • suggestion: a code to report instead (placeholder X) or in addition (bilateral).
  • guidance: additional review guidance, where applicable.
An Excludes1 finding (abridged)
{
  "rule": "excludes1",
  "severity": "review",
  "codes": [
    "E10.9",
    "E11.9"
  ],
  "message": "E10.9 and E11.9 are not normally reported together.",
  "notes": [
    {
      "note": "type 2 diabetes mellitus (E11.-)",
      "carrier": "E10",
      "rule_id": "excludes1:E10:9"
    },
    {
      "note": "type 1 diabetes mellitus (E10.-)",
      "carrier": "E11",
      "rule_id": "excludes1:E11:8"
    }
  ],
  "guidance": "They may be reported together only when the two conditions are unrelated (ICD-10-CM Guidelines I.A.12.a)."
}
A Code First finding (abridged)
{
  "rule": "code_first",
  "severity": "review",
  "codes": [
    "F02.80",
    "G20.A1"
  ],
  "message": "G20.A1 is listed after F02.80; the Code First note asks for it to be sequenced first.",
  "note": "Parkinson's disease (G20.-)",
  "carrier": "F02",
  "rule_id": "code_first:F02:18"
}

Errors

Errors use standard HTTP status codes and a consistent response body. error.code is a stable identifier for programmatic handling; error.message is a human-readable description.

StatusMeaning and error codes
400The request is malformed or invalid: invalid_json, unknown_field, invalid_field, too_few_codes, too_many_codes, invalid_code_format, conflicting_release, invalid_query
403Request verification failed: bot_check_required, bot_check_failed
404The code, block, chapter, code set or path does not exist: code_not_found, block_not_found, chapter_not_found, release_not_found, not_found
405The method is not supported for this path (see the Allow header): method_not_allowed
413The request body exceeds 4,096 bytes: body_too_large
415The request body is not application/json: unsupported_media_type
429A rate limit was exceeded (see Access and limits): rate_limited, daily_limit_reached
500An unexpected error occurred: internal_error
503The service or its data is temporarily unavailable: data_unavailable, service_unavailable
400: one code
{
  "error": {
    "code": "too_few_codes",
    "message": "Send at least 2 different codes."
  }
}
404: no such code
{
  "error": {
    "code": "code_not_found",
    "message": "Z99.999 is not a code in the FY2027 code set."
  }
}

Check

Validate codes

POST/check

Validates 2 to 10 diagnosis codes against the coding rules and returns each finding with the note that supports it.

Parameters

codesstring[] · required
2 to 10 distinct codes in claim order. Order is significant for the Code First, manifestation and principal diagnosis rules.
rulesstring[]
The rules to run (see Rules). Omit to run all rules.
patient.ageinteger
Patient age in whole years, 0 to 124. Required for the age rule.
releasestring
The code set to use (see Code sets). Alternatively, send date_of_service; not both.

Response fields

statusstring
clear or review.
releasestring
The code set used for the response.
codes[]array
Each submitted code: code (with the decimal point), known (whether it is in the code set), description (null when not known) and billable.
findings[]array
The items to review (see Findings).
checkedstring[]
The rules that were run.
curl https://api.icd10rules.com/v1/check \
  -H "Content-Type: application/json" \
  -d '{
    "codes": [
      "E10.9",
      "E11.9",
      "S52.001"
    ],
    "patient": {
      "age": 45
    }
  }'
Response (abridged)
{
  "status": "review",
  "release": "2027.0",
  "codes": [
    {
      "code": "E10.9",
      "known": true,
      "description": "Type 1 diabetes mellitus without complications",
      "billable": true
    },
    {
      "code": "E11.9",
      "known": true,
      "description": "Type 2 diabetes mellitus without complications",
      "billable": true
    },
    {
      "code": "S52.001",
      "known": true,
      "description": "Unspecified fracture of upper end of right ulna",
      "billable": false
    }
  ],
  "findings": [
    {
      "rule": "excludes1",
      "severity": "review",
      "codes": [
        "E10.9",
        "E11.9"
      ],
      "message": "E10.9 and E11.9 are not normally reported together.",
      "notes": [
        {
          "note": "type 2 diabetes mellitus (E11.-)",
          "carrier": "E10",
          "rule_id": "excludes1:E10:9"
        },
        {
          "note": "type 1 diabetes mellitus (E10.-)",
          "carrier": "E11",
          "rule_id": "excludes1:E11:8"
        }
      ],
      "guidance": "They may be reported together only when the two conditions are unrelated (ICD-10-CM Guidelines I.A.12.a)."
    },
    {
      "rule": "seventh_char",
      "severity": "error",
      "codes": [
        "S52.001"
      ],
      "message": "S52.001 needs a 7th character: A, B, C, D, E, F, G, H, J, K, M, N, P, Q, R or S.",
      "options": [
        {
          "character": "A",
          "meaning": "initial encounter for closed fracture"
        },
        {
          "character": "B",
          "meaning": "initial encounter for open fracture type I or II"
        },
        {
          "character": "C",
          "meaning": "initial encounter for open fracture type IIIA, IIIB, or IIIC"
        }
      ]
    }
  ],
  "checked": [
    "valid_code",
    "excludes1",
    "code_first",
    "seventh_char",
    "age",
    "manifestation",
    "principal",
    "laterality"
  ]
}

Codes

Retrieve a code

GET/codes/{code}

Returns a code with its description, its position in the code set, the edits that apply to it, its 7th characters, and every applicable note, including those inherited from its parent codes, block and chapter.

Parameters

codepath · required
An ICD-10-CM code, with or without the decimal point.
releasestring
The code set to use (see Code sets). Alternatively, send date_of_service.

Response fields

billableboolean
false for a header code that requires additional characters.
chapter, blocks[]object, array
The chapter and blocks that contain the code, outermost block first.
age_rangeobject
low and high in years, or null when no age edit applies.
manifestation, not_principalboolean
Whether the code is a manifestation code, and whether CMS does not accept it as the first-listed diagnosis on an outpatient claim.
seventh_charactersobject
applies_from (the code at which the definition is published) and its options, or null.
notes[]array
Each note: type (includes, excludes1, excludes2, code_first, use_additional_code, code_also), text as published, carrier, level (code, block or chapter) and inherited.
curl "https://api.icd10rules.com/v1/codes/E11.9"
Response (abridged)
{
  "release": "2027.0",
  "code": "E11.9",
  "description": "Type 2 diabetes mellitus without complications",
  "short_description": "Type 2 diabetes mellitus without complications",
  "billable": true,
  "chapter": {
    "number": 4,
    "name": "Endocrine, nutritional and metabolic diseases"
  },
  "blocks": [
    {
      "id": "E08-E13",
      "name": "Diabetes mellitus"
    }
  ],
  "age_range": null,
  "manifestation": false,
  "not_principal": false,
  "seventh_characters": null,
  "notes": [
    {
      "type": "includes",
      "text": "diabetes (mellitus) due to insulin secretory defect\ndiabetes NOS\ninsulin resistant diabetes (mellitus)",
      "carrier": "E11",
      "level": "code",
      "inherited": true
    },
    {
      "type": "excludes1",
      "text": "type 2 diabetes mellitus, without complications in remission (E11.A)",
      "carrier": "E11.9",
      "level": "code",
      "inherited": false
    },
    {
      "type": "excludes1",
      "text": "diabetes mellitus due to underlying condition (E08.-)",
      "carrier": "E11",
      "level": "code",
      "inherited": true
    }
  ]
}

Search

Browse

Browse a chapter or block

GET/browse

Lists the codes in a chapter or block in tabular order. Returns 100 results per page.

Parameters

chapterinteger
The chapter number.
blockstring
A block id, such as E08-E13. Send chapter, block or both; a block must belong to the chapter sent with it.
pageinteger
1 to 1,000. Default 1.
releasestring
The code set to use (see Code sets). Alternatively, send date_of_service.

Response fields

chapter, blockobject
The chapter or block listed. A block includes its parent block, or null.
total, has_moreinteger, boolean
The total number of codes, and whether another page is available.
results[]array
Each code with its description and billable.
curl "https://api.icd10rules.com/v1/browse?block=E08-E13"
Response (abridged)
{
  "release": "2027.0",
  "chapter": {
    "number": 4,
    "name": "Endocrine, nutritional and metabolic diseases"
  },
  "block": {
    "id": "E08-E13",
    "name": "Diabetes mellitus",
    "parent": null
  },
  "page": 1,
  "page_size": 100,
  "total": 582,
  "has_more": true,
  "results": [
    {
      "code": "E08",
      "description": "Diabetes mellitus due to underlying condition",
      "billable": false
    },
    {
      "code": "E08.0",
      "description": "Diabetes mellitus due to underlying condition with hyperosmolarity",
      "billable": false
    },
    {
      "code": "E08.00",
      "description": "Diabetes mellitus due to underlying condition with hyperosmolarity without nonketotic hyperglycemic-hyperosmolar coma (NKHHC)",
      "billable": true
    }
  ]
}

Service

Code sets

GET/releases

Lists the available code sets, newest first, with the effective dates of each and the current default.

Response fields

releases[]array
Each code set: id (the value to send as release), code_set, effective_from, effective_to (null when open-ended), build and current.
defaultstring
The code set used when a request specifies none.
curl "https://api.icd10rules.com/v1/releases"
Response
{
  "releases": [
    {
      "id": "2027.0",
      "code_set": "FY2027",
      "effective_from": "2026-10-01",
      "effective_to": "2027-09-30",
      "build": 2,
      "current": true
    },
    {
      "id": "2026.1",
      "code_set": "FY2026 April update",
      "effective_from": "2026-04-01",
      "effective_to": "2026-09-30",
      "build": 1,
      "current": false
    },
    {
      "id": "2026.0",
      "code_set": "FY2026",
      "effective_from": "2025-10-01",
      "effective_to": "2026-03-31",
      "build": 2,
      "current": false
    }
  ],
  "default": "2027.0"
}

Health

GET/health

Reports whether the service is available and the data for every code set is in place. Returns `200` with `ok`, or `503` with the same body and `degraded`.

Response fields

statusstring
ok or degraded.
versionobject
The API version and the running build.
releases[]array
For each code set: its build, the checksum of its rules, and whether its database records match.
curl "https://api.icd10rules.com/v1/health"
Response
{
  "status": "ok",
  "version": {
    "api": "0.1.0",
    "worker_version_id": "013df0db-7d95-4ec4-b947-bda1cf5b2821",
    "worker_version_tag": null
  },
  "releases": [
    {
      "id": "2027.0",
      "build": 2,
      "rules_sha256": "26831b1f068477ea413712079cbe1e63d646a33fceed578a075a0218eb9c0c96",
      "database": "ok"
    },
    {
      "id": "2026.1",
      "build": 1,
      "rules_sha256": "c892039ceb9e39c1cfb51e5c9d3ad9480383773086ac5d087b9689ea1bcc0458",
      "database": "ok"
    },
    {
      "id": "2026.0",
      "build": 2,
      "rules_sha256": "cc5c76ca138425a8a945818bb860f9ad78d977eb9ec573d3fecd5a259c7ec739",
      "database": "ok"
    }
  ]
}