ICD-10 API Documentation

{beta}


Cheat sheet


Endpoints

Specific ICD-10 code

Call

Use the URL format api.aqua.io/codes/beta/icd10/CODE_NAME.json via an HTTP GET request.

Code name should be formatted so that the decimal ('.') is replaced with a dash ('-'). e.g., R50.9 should be formatted as R50-9.

Response

Field
Explanation
Example Value
name
The ICD-10 code.
R50.9
description
The condition the code describes.
Fever, unspecified
explanation
Additional explanation of how to properly use or understand the code, if any.
INCLUDES:\n Fever NOS\n Fever of unknown origin [FUO]\n Fever with chills\n Fever with rigors...
wikipedia_url
Relevant Wikipedia link, if available.
http://en.wikipedia.org/wiki/Fever
valid_years
An array of years for which this code is valid (i.e., was included in the CMS ICD-10-CM file for that year). (More about valid code years.)
["2012", "2013", "2014"]
parent
The "parent" or ascendant code. If the code is already top-level, value will be "null".
{"name": "R50", "description": "Fever of other and unknown origin", "explanation": "EXCLUDES:\nchills without fever (R68.83)\nfebrile convulsions (R56.0-)\nfever of unknown origin during labor (O75.2)\nfever of unknown origin in newborn (P81.9)\nhypothermia due to illness (R68.0)\nmalignant hyperthermia due to anesthesia (T88.3)\npuerperal pyrexia NOS (O86.4)", "url": "https://api.aqua.io/codes/icd10/2013/r50"}
children
An array of "children" or descendant codes. If the code is bottom-level, returns an empty array.
[ ]
equivalents
An array of ICD-9 code equivalents, including equivalancy flag and translation. (More about code equivalents.)
[{"equivalent":{"name":"780.60","description":"Fever, unspecified","explanation":"Chills with fever\r\nFever NOS\r\nFever of unknown origin (FUO)\r\nHyperpyrexia NOS\r\nPyrexia NOS\r\nPyrexia of unknown origin\r\nExcludes:\tchills without fever (780.64)\r\nneonatal fever (778.4)\r\npyrexia of unknown origin (during):\r\nin newborn (778.4)\r\nlabor (659.2)\r\nthe puerperium (672)","flag":"10000", "equivalency_strength":"nearly identical meaning (but not an exact match)","url": "https://api.aqua.io/codes/ icd9/2011/780-60.json"}}]
hcc_group_2014
HCC grouping for 2014 (may be 'null'). (Why are all ICD-10 HCC groups 'null'?)
null
hcc_group_2013
HCC grouping for 2013 (may be 'null'). (Why are all ICD-10 HCC groups 'null'?)
null
rxhcc_group_2014
RxHCC grouping for 2014 (may be 'null'). (Why are all ICD-10 HCC groups 'null'?)
null
pace_esrd_group_2014
PACE/ESRD grouping for 2014 (may be 'null'). (Why are all ICD-10 HCC groups 'null'?)
null
Full output for ICD-10 code R50.9

Good to know

  • The call URL may specify a code modification year, e.g. api.aqua.io/codes/beta/icd10/2013/r50-9.json Only modifications maintained by the CMS and published online are available. Not specifying a year returns the codes from all available years.

  • Calls that do not specify an API version will default to the most current API, e.g. api.aqua.io/codes/icd10/r50-9.json .

    Since future API versions may break implementations using prior versions, however, we strongly recommend specifying a version.
  • A malformed code request will return a 404 Status Error and, in many cases, an array of possible matches. For example api.aqua.io/codes/beta/icd10/250.json returns

    {"possible_matches":[{"name":"A50","description":"Congenital syphilis","explanation":"","url":"https://api.aqua.io/codes/icd10/2013/a50.json"},...]

    This can be useful for returning a 'did you mean...?' list of options to a user, if an inputted code contains a typo.

All top-level codes

Call

Use the URL format api.aqua.io/codes/beta/icd10.json via an HTTP GET request.

Response

Returns a JSON array of all top-level ICD-10 codes, each containing the following fields:

Field
Explanation
Example Value
name
The ICD-9 code.
A00
description
The condition the code describes.
Cholera
url
API URL for the code.
https://api.aqua.io/codes/icd10/2013/a00.json
Output for all ICD-10 codes.

Good to know

  • As with individual codes, call URL may specify a code modification year, e.g. api.aqua.io/codes/beta/icd10/2013.json

  • Calls that do not specify an API version will default to the most current API, e.g. api.aqua.io/codes/icd10.json .

    Since future API versions may break implementations using prior versioms, however, we strongly recommend specifying a version.

Search

Call

Use the URL format GET .../icd10.json?utf8=✓&q%5BSEARCH_PARAMETERS%5D=QUERY via an HTTP GET request.

Response

Returns a JSON array of matching results, each containing the following fields:

Field
Explanation
Example Value
name
The ICD-10 code.
A92.30
description
The condition the code describes.
West Nile virus infection, unspecified
url
API URL for the code.
https://api.aquahost.com/codes/icd10/2013/a92-30.json

Query Parameters

A search may query a code 'name', 'description', or a both fields ('name_or_description'). Each field may be queried using any of the following suffixes:

Suffix
Explanation
Example Implementation
X_cont=Y
Field X contains Y
...%5Bdescription_cont%5D=west_nile...
X_start=Y
Field X starts with Y
...%5Bname_start%5D=V...
X_end=Y
Field X ends with Y
...%5Bname_end%5D=.01...

FAQs

What are the benefits of using ICD codes in developing an app?

ICD codes are the internationally-recognized standard for classifying medical diagnoses. They feature prominently in EHRs and other clinical systems that gather health data, as well as in most standards for transmitting healthcare data, like HL7.

Using ICD codes instead of "free form" descriptions of diseases in an app helps ensure interoperability with systems that collect healthcare data. This can mean not only making consumer-generated data more relevant to the clinical environment, but also providing a key for consumers to interpret clinical data in plain language.

What are ICD-9 equivalents? How are they determined?

Most medical coding and billing in the U.S. is currently transitioning from using ICD-9 to ICD-10. The equivalents provide a roadmap for converting the codes from one standard to the other, as well as for providing a helpful backward reference to those not familiar with the ICD-10 code system.

All equivalents in the API are mapped according to the ICD-10 General Equivalance Mappings (GEM) provided by the Centers for Medicare & Medicaid Services (CMS).

Why do equivalents have 'flag' and 'equivalency_strength' fields?

Not all the equivalents provided in the CMS GEM are identical matches--some codes have multiple possible matches, since the target code system may be more or less specific than the source code system.

A flag is a five digit code in the CMS GEM meant to provide a guide in properly mapping a code from one system to the other. An explanation of the flags can be found here.

An equivalency_strength field is a semantic interpretation of the CMS GEM flags, for those who do not have the time to closely familiarize themselves with the flag system, or build logic to convert the flags to a semantic system.The equivalencey_strengths are provided as a courtesy, and should not be considered as superceding or replacing the flag system.

Are the equivalents bi-directional?

No, CMS provides two different lists for ICD-9-to-10 and ICD-10-to-9 conversion. Sometimes, there is no single proper equivalency, and multiple options are provided. The equivalents given for each API reflect this.

Which ICD-10 codeset years are included?

All the years available from CMS: 2012, 2013, and 2014

Why are all the HCC groupings for ICD-10 codes returned as 'null'?

Currently, CMS does not publish HCC groupings for ICD-10 codes, only ICD-9 codes. In anticipation that CMS may publish such mappings in future years, however, and to maintain consistency between the formats of our ICD-9 and ICD-10 APIs, we have still decided to include these field names for individual ICD-10 codes.

If needed, a strategy for getting HCC groupings for ICD-10 codes might include mapping the ICD-10 code to it's ICD-9 equivalent(s) and pulling the groupings from the equivalent(s).



Coding APIs

Code Search