The ICD10 Rules API is in private preview. Contact us to arrange access for your software.
Request accessAPI 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.
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.
| Endpoint | Purpose |
|---|---|
POST /check | Validate 2 to 10 diagnosis codes against the coding rules |
GET /codes/{code} | Retrieve a code with its description and notes |
GET /search | Search by code, range or description |
GET /browse | List the codes in a chapter or block |
GET /releases | List the available code sets |
GET /health | Report 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.
https://api.icd10rules.com/v1Access and limits
The API is in private preview. Access for your own software is arranged individually: contact [email protected] 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:
| Endpoint | Default limit |
|---|---|
POST /check | 10 per minute, 30 per day |
GET /codes/{code}; GET /search by code, prefix or range | 60 per minute, 300 per day |
GET /search by description; GET /browse | 20 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:
| release | Code set | Effective |
|---|---|---|
2027.0 | FY2027 | 2026-10-01 to 2027-09-30 |
2026.1 | FY2026 April update | 2026-04-01 to 2026-09-30 |
2026.0 | FY2026 | 2025-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.
GET /v1/codes/E11.9?date_of_service=2026-05-01{
"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.
| Rule | Flags |
|---|---|
valid_code | A 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. |
excludes1 | Two codes that an Excludes1 note indicates are not normally reported together. |
code_first | A code listed before the underlying condition that its Code First note requires to be sequenced first. |
seventh_char | A code that requires a 7th character, or a 7th character that is not valid for the code. |
age | A code whose age range does not include the patient age provided. |
manifestation | A manifestation code listed first, or listed with no preceding underlying condition named by its Code First note. |
principal | A first-listed code that CMS does not accept in that position: an external cause code or an unacceptable principal diagnosis. |
laterality | An unspecified-side code where side-specific codes exist, or right and left codes where a bilateral code exists. |
POST /v1/check{
"codes": [
"E10.9",
"E11.9",
"I10"
],
"rules": [
"excludes1"
]
}{
"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. Eachnoteas published, with itscarrier(a code, block or chapter).noteandcarrier: 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.
{
"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": "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.
| Status | Meaning and error codes |
|---|---|
| 400 | The request is malformed or invalid: invalid_json, unknown_field, invalid_field, too_few_codes, too_many_codes, invalid_code_format, conflicting_release, invalid_query |
| 403 | Request verification failed: bot_check_required, bot_check_failed |
| 404 | The code, block, chapter, code set or path does not exist: code_not_found, block_not_found, chapter_not_found, release_not_found, not_found |
| 405 | The method is not supported for this path (see the Allow header): method_not_allowed |
| 413 | The request body exceeds 4,096 bytes: body_too_large |
| 415 | The request body is not application/json: unsupported_media_type |
| 429 | A rate limit was exceeded (see Access and limits): rate_limited, daily_limit_reached |
| 500 | An unexpected error occurred: internal_error |
| 503 | The service or its data is temporarily unavailable: data_unavailable, service_unavailable |
{
"error": {
"code": "too_few_codes",
"message": "Send at least 2 different codes."
}
}{
"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
agerule. releasestring- The code set to use (see Code sets). Alternatively, send
date_of_service; not both.
Response fields
statusstringclearorreview.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(nullwhen not known) andbillable. 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
}
}'{
"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
billablebooleanfalsefor a header code that requires additional characters.chapter, blocks[]object, array- The chapter and blocks that contain the code, outermost block first.
age_rangeobjectlowandhighin years, ornullwhen 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_charactersobjectapplies_from(the code at which the definition is published) and itsoptions, ornull.notes[]array- Each note:
type(includes,excludes1,excludes2,code_first,use_additional_code,code_also),textas published,carrier,level(code,blockorchapter) andinherited.
curl "https://api.icd10rules.com/v1/codes/E11.9"{
"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
Search codes
GET/search
Searches codes by code, prefix, range or description. Returns 25 results per page.
Parameters
qstring · required- 3 to 100 characters. A code or prefix (
E11.6,E11-) returns matches in code order; a range (E08-E13) returns codes in tabular order; any other text is matched against descriptions, best match first, with the last word treated as a prefix. Description searches return at most 4 pages. cursorstring- The
nextvalue from the previous page, sent with the sameq, to retrieve the next page. releasestring- The code set to use (see Code sets). Alternatively, send
date_of_service.
Response fields
modestring- How
qwas interpreted:code,rangeorwords. results[]array- Each code with its
descriptionandbillable. has_more, nextboolean, string- Whether another page is available, and the cursor for it (
nullon the last page).
curl "https://api.icd10rules.com/v1/search?q=diabetes"{
"release": "2027.0",
"query": "diabetes",
"mode": "words",
"page_size": 25,
"has_more": true,
"next": "w.2",
"results": [
{
"code": "E10.21",
"description": "Type 1 diabetes mellitus with diabetic nephropathy",
"billable": true
},
{
"code": "E10.36",
"description": "Type 1 diabetes mellitus with diabetic cataract",
"billable": true
},
{
"code": "E10.41",
"description": "Type 1 diabetes mellitus with diabetic mononeuropathy",
"billable": true
}
]
}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. Sendchapter,blockor 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
parentblock, ornull. total, has_moreinteger, boolean- The total number of codes, and whether another page is available.
results[]array- Each code with its
descriptionandbillable.
curl "https://api.icd10rules.com/v1/browse?block=E08-E13"{
"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 asrelease),code_set,effective_from,effective_to(nullwhen open-ended),buildandcurrent. defaultstring- The code set used when a request specifies none.
curl "https://api.icd10rules.com/v1/releases"{
"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
statusstringokordegraded.versionobject- The API version and the running build.
releases[]array- For each code set: its
build, the checksum of its rules, and whether itsdatabaserecords match.
curl "https://api.icd10rules.com/v1/health"{
"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"
}
]
}