Introduction
Shaip presents its innovative "ICD10CM API", adept at transforming unstructured EHR data into precise ICD-10-CM codes, which are standardized codes for categorizing medical diagnoses and procedures. Harnessing advanced NLP, the API delivers exact ICD-10-CM code recommendations and extracts pertinent clinical evidence, deepening patient data comprehension. Noteworthy features include the API's ability to give accurate, context-driven code suggestions and its seamless REST API design, allowing for easy integration across varied healthcare systems. With Shaip's ICD10CM API, healthcare experts can automate medical coding, achieving enhanced clinical insights and fostering standardized practices in the continually evolving healthcare domain.
By harnessing Shaip's ICD10CM API, healthcare professionals and researchers gain access to a powerful tool that automates and enhances the accuracy of medical coding. Embrace our advanced API to unlock new dimensions of clinical insights, streamline data processing, and promote standardized medical practices in the dynamic landscape of healthcare.
Authentication
The ICD10CM API requires authentication using an API key to ensure secure access and prevent unauthorized usage. Upon registration and subscription to the API service, you will receive a unique API key that must be included in the request headers when making API calls.
To maintain the security of your API key, it is essential to keep it confidential and avoid sharing it in publicly accessible areas, such as client-side code, version control repositories, or public forums. Your API key acts as your account's access credential, granting the necessary privileges to interact with the ICD10CM API.
To authenticate your API requests, include the x-api-key header in each POST request, similar to the example curl request provided below:
API Endpoint:
- URL: https://nlpapi.healthcarenlp.com/v1/icd10cm
- Method: POST
- Headers:Content-Type: "application/json"
x-api-key:{YOUR_UNIQUE_API_KEY}
By ensuring that you include the appropriate authentication details and headers with each API call, you can experience uninterrupted access to the ICD10CM API's powerful functionality. Our robust authentication process is designed to protect sensitive medical data and ensure that only authorized users can leverage this valuable service.
Remember to replace YOUR_API_KEY with your actual API key provided to you upon registration and subscription to the ICD10CM API service. With this curl request and the correct authentication header, you can access the powerful functionality of the ICD10CM API to convert unstructured medical text into accurate ICD10CM codes and extract valuable clinical evidence from the medical documents.
CURL
1curl -X POST "https://nlpapi.healthcarenlp.com/v1/icd10cm"
2
3 -H "Content-Type: application/json"
4
5 -H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1"
6
7 -d '{
8 "data": "{YOUR_UNSTRUCTURED_TEXT}"
9 }'
10API Request
Request Parameter
To make the most of Shaip's ICD10CM API, you must create a well-structured HTTP request with the essential parameter:
content (String, Required): This crucial field should hold the unstructured medical document's content in the form of a string. The content must precisely represent the patient's clinical information, such as Electronic Health Record (EHR) data or any pertinent medical text. It is essential to ensure that the content is properly formatted and adheres to the API's guidelines to receive accurate ICD10CM code recommendations.
For your convenience, you can employ the following CURL command to craft a well-structured HTTP request with the mandatory parameter:
CURL
JAVA
Python
NodeJS
Ruby
PHP
GO
.NET(C#)
1curl -X POST "https://nlpapi.healthcarenlp.com/v1/icd10cm"
2
3 -H "Content-Type: application/json"
4
5 -H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1"
6
7 -d '{
8 "data": "PATIENT DIAGNOSIS:
91. Hypertension
102. Diabetes mellitus type 2
113. Acute bronchitis"
12 }'
13API Response
Response Parameter
The ICD10CM API provides a structured and comprehensive response to facilitate the seamless integration of ICD-10-CM codes into healthcare systems. The response comprises three main tables - Code, Evidence, and TextSpan, each containing crucial details as follows:
- Code
- codingSystem (Enum, Required): This field indicates the coding system from which the ICD-10-CM code originates. For this API, the value will always be "ICD10CM."
- value (String, Required): This field contains the actual value of the ICD-10-CM code, such as "E11.9" representing a specific diagnosis or medical condition.
- evidence (List<Evidence>, Optional): This field holds a list of evidence (if available) that supports the recommended ICD-10-CM code. Each element in the list corresponds to a piece of evidence contributing to the code recommendation.
- textSpan (TextSpan, Required): This field represents the content of the entity that serves as evidence for the recommended ICD-10-CM code. It points to the specific portion of the medical document where the evidence is extracted.
- beginOffset (Integer, Required): This field contains the calculated beginning offset of the textSpan content within the original medical document. The offset refers to the character position where the textSpan starts.
- text (String, Required): This field contains the actual content of the textSpan. It represents the extracted text that serves as evidence for the ICD-10-CM code recommendation.
- certainty (Enum, Required): This field contains the certainty value of the detected entity from a predefined list of certainty values. The certainty value indicates the negation in the entity's presence or accuracy.
- status (Enum, Required): This field contains the status value of the detected entity from a predefined list of status values. The status value indicates the temporal context, encompassing current, historical, future, and family history-related information in the entity's presence or accuracy.
- section (TextSpan, Required): This field contains the text span describing the section from where the evidence has been detected. It helps identify the context of the evidence within the medical document.
The well-organized response from the ICD10CM API ensures that healthcare applications can effortlessly access and utilize the recommended ICD-10-CM codes along with the corresponding evidence, enabling precise medical coding and enhanced patient data analysis.
Response Parameter Values
Coding System Values
- ICD10CM : ICD-10-CM (International Classification of Diseases, 10th Revision, Clinical Modification) is a standardized coding system used in healthcare to classify and represent medical diagnoses and procedures, providing a common language for medical information exchange and billing purposes.
Certainty Values
- POSITIVE - A positive certainty indicates the entities are confirmed and present positively in the patient’s record. e.g. The patient has hypertension and is on diuretics. In this example "hypertension" is positive and the patient is taking "diuretics" which also indicates that it is positive.
- POSSIBLE_POSITIVE - A possible positive certainty indicates the entities are present but are not accurate and valid. e.g. The wound of the patient appears to be granulating. In this example the word "appears to be" is possibly positive as it is not confirmed evidence.
- NEGATIVE - A negative certainty indicates the entities are not present. e.g. The patient does not have vomiting and nausea. In this example evidence "vomiting" and "nausea" are not present in the patient.
- POSSIBLE_NEGATIVE - A possible negative certainty indicates the entities are not totally absent but are present insignificantly. e.g. The patient’s wound abscess was resolving. In this example "resolving" is a possible negative word which means wound abscess is not treated completely and hence cannot be marked as negative.
- UNCERTAIN - Uncertainty indicates the state of doubt to determine. It is the situation in which something is not known or not certain. e.g. The doctor was unable to determine the cause of the swelling. In this example "unable to determine" indicates uncertainty.
- CONDITIONAL - Conditional indicates hypothetical situations and their consequences. e.g. The doctor said that the patient should also come back if he develops pain, fever, nausea, vomiting, or any other concerning symptoms. In this example "if he develops" is conditional.
- FAMILY_HISTORY - Family history provides the information of all the diseases and illnesses within the family of the patient. e.g. The patient has a family history of hypertension. This example shows that "hypertension" was present in his family.
- FUTURISTIC - It indicates the events that will happen after the present time. E.g. The doctor said that he will check the wound after 5 days. In this example "will check" indicates the future status.
Status Values
- CURRENT - Current status defines the present time. It includes the things happening, being used or done now. e.g. The patient is suffering from hypertension and diabetes mellitus. This example indicates "hypertension" and "diabetes mellitus" are present in the patient currently.
- HISTORY - History describes the personal history of the patient. It includes the diseases, procedures etc which he had in the past. e.g. The patient has a history of right arm fracture. This example indicates that the patient suffered from "right arm fracture" in the past.
- FAMILY_HISTORY - Family history provides the information of all the diseases and illnesses within the family of the patient. e.g. The patient has a family history of hypertension. This example shows that "hypertension" was present in his family.
- FUTURISTIC - It indicates the events that will happen after the present time. E.g. The doctor said that he will check the wound after 5 days. In this example "will check" indicates the future status.
JSON
1{
2 "icd10cmcodes": [
3 {
4 "code": "I10",
5 "similarity": 1,
6 "codeMatchText": "hypertension",
7 "rank": 42,
8 "phrases": [
9 {
10 "begin": 22,
11 "end": 34,
12 "certainty": "POSITIVE",
13 "section": "Report Unknown Section",
14 "status": "CURRENT",
15 "text": "Hypertension"
16 }
17 ]
18 },
19 {
20 "code": "E11.9",
21 "similarity": 1,
22 "codeMatchText": "diabetes mellitus",
23 "rank": 80,
24 "phrases": [
25 {
26 "begin": 35,
27 "end": 60,
28 "certainty": "POSITIVE",
29 "section": "Report Unknown Section",
30 "status": "CURRENT",
31 "text": "2. Diabetes mellitus type"
32 }
33 ]
34 },
35 {
36 "code": "J40",
37 "similarity": 1,
38 "codeMatchText": "bronchitis",
39 "rank": 107,
40 "phrases": [
41 {
42 "begin": 72,
43 "end": 82,
44 "certainty": "POSITIVE",
45 "section": "Report Unknown Section",
46 "status": "CURRENT",
47 "text": "bronchitis"
48 }
49 ]
50 }
51 ],
52 "requestId": 269
53}Error
When interacting with the Shaip API, you may encounter specific error codes, along with standard HTTP response statuses and corresponding error messages in the response body. Below is a table summarizing the possible error codes, along with their respective HTTP status and updated response body:
| Response Code | HTTP Status | Response Body |
| 400 | Bad Request | { "error": "The request was unacceptable, often due to missing a required parameter." } |
| 401 | Unauthorized | { "error": "No valid API key provided." } |
| 402 | Token Expired | { "error": "Token expired. Please contact administrator" } |
| 403 | Forbidden | { "error": "The API key doesn't have permissions to perform the request." } |
| 429 | Trial Quota Excceded | { "error": "Trial quota for API calls exceeded. Please upgrade your plan or try again later." } |
| 500 | Internal Server Error | { "error": "Something went wrong on the server's end. Please try again later." } |
400
401
402
403
429
500
1{
2 "error": "The request was unacceptable, often due to missing a required parameter."
3}