Logo
Introduction
Shaip introduces a revolutionary "SNOMED" API, designed to transform unstructured medical texts like EHR data into precise SNOMED codes, the standardized language representing medical concepts. Powered by advanced Natural Language Processing, the API offers accurate SNOMED code suggestions, also highlighting clinical evidence aligned with the codes. With features such as precise code recommendations and effortless REST API integration, this tool optimizes medical coding, making it more efficient and standardized. Healthcare professionals leveraging Shaip's API can achieve streamlined data processing, enhanced clinical insights, and consistent healthcare practices.
Authentication
The SNOMED API requires authentication using an API key to ensure secure access and prevent unauthorized usage. When making requests to the API, you must include the API key in the request headers. The x-api-key header should contain your unique API key, which will be provided to you upon registration and subscription to the API service.
Please ensure that you keep your API key confidential and do not share it in publicly accessible areas, such as client-side code, version control repositories, or public forums. The API key grants access to your account and holds the necessary privileges to interact with the SNOMED API.
To authenticate your API requests, include the x-api-key header in each POST request as shown in the example curl request. This way, our server can verify your credentials and provide access to the SNOMED service.
API Endpoint:
Ensure that you include the appropriate authentication details and headers with each API call to experience uninterrupted access to the SNOMED API's powerful functionality. Our secure authentication process is designed to protect sensitive medical data and ensure that only authorized users can utilize this valuable service.
Remember to replace YOUR_API_KEY with your actual API key provided to you upon registration and subscription to the SNOMED API service. With this curl request and the correct authentication header, you can access the powerful functionality of the SNOMED API to convert unstructured medical text into accurate SNOMED codes and extract valuable clinical evidence from the medical documents.
CURL
1curl -X POST "https://haiapi.shaip.com/snomed_output" 
2
3     -H "Content-Type: application/json" 
4
5     -H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1" 
6
7     -d '{
8            "data": "{YOUR_UNSTRUCTURED_TEXT}"
9         }'
10
API Request
Request Parameter
To leverage the capabilities of Shaip's SNOMED Code Recommendation API, you need to craft a well-structured HTTP request with the following essential parameter:
content (String, Required): This vital field should contain the unstructured medical document's content in the form of a string. The content must accurately represent the patient's clinical information, such as Electronic Health Record (EHR) data or any relevant medical text. Ensure that the content is properly formatted and adheres to the API's guidelines to receive precise SNOMED code recommendations.
To utilize Shaip's SNOMED Code Recommendation API, you can use the following CURL command to craft a well-structured HTTP request with the required parameter.
In this CURL request, ensure that you replace the placeholder data in the "content" field with the actual unstructured medical document's content. This content should accurately represent the patient's clinical information, such as Electronic Health Record (EHR) data or any relevant medical text. Properly format the content according to the API's guidelines to receive precise SNOMED code recommendations.
CURL
JAVA
Python
NodeJS
Ruby
PHP
GO
.NET(C#)
1curl -X POST "https://haiapi.shaip.com/snomed_output" 
2
3     -H "Content-Type: application/json" 
4
5     -H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1" 
6
7     -d '{
8            "content": "DIAGNOSIS:
91. Possible NSTEMI
102. Possible CHF
11
12DISCHARGE DIAGNOSIS:
131. Congestive heart failure
142. Hypertension, malignant
153. History of seizures
164. Diabetic neuropathy
175. Anxiety
186. Obstructive sleep apnea
19
20DISCHARGE MEDS:
21SAME AS NURSING HOME MEDS:
22Humulin 100 units q.d .
23Xanax 500 mg two q.h.s.
24Coreg 6.25 mg oral tablet q.d .
25Dilantin 100 mg capsule q.d . "
26         }'
27
API Response
Response Parameter
The SNOMED Code Recommendation API provides a structured and comprehensive response to aid in the efficient integration of SNOMED codes into healthcare systems. The response consists of three main parameters - Code, Evidence, and TextSpan, each containing essential details as follows:
  • Code
      • codingSystem (Enum, Required): This field indicates the coding system from which the SNOMED code is derived. For this API, the value will always be "SNOMED."
      • value (String, Required): This field contains the actual value of the SNOMED code, such as "38341003" representing a specific medical concept.
      • evidence (List<Evidence>, Optional): This field contains a list of evidence (if available) that supports the recommended SNOMED 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 SNOMED code. It refers 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 SNOMED code recommendation.
        • certainty (Enum, Required): This field contains the certainty value of the detected entity from the following list: [List of Certainty Values]. The certainty value indicates the level of confidence 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.
Response Parameter Values
Coding System Values
  • SNOMED : SNOMED (Systematized Nomenclature of Medicine) is a standardized clinical terminology used to represent medical concepts and entities with unique alphanumeric codes. It enables accurate communication and data exchange within the healthcare industry.
    • 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.
    • JSON
    1{
2  "codes": [
3    {
4      "codingSystem": "SNOMED",
5      "evidence": [
6        {
7          "certainty": "POSITIVE",
8          "status": "CURRENT",
9          "textSpan": {
10            "beginOffset": 98,
11            "text": "Hypertension"
12          }
13        },
14        {
15          "certainty": "POSITIVE",
16          "status": "CURRENT",
17          "textSpan": {
18            "beginOffset": 112,
19            "text": "malignant"
20          }
21        }
22      ],
23      "status": "CURRENT",
24      "value": "70272006"
25    },
26    {
27      "codingSystem": "SNOMED",
28      "evidence": [
29        {
30          "certainty": "POSITIVE",
31          "status": "CURRENT",
32          "textSpan": {
33            "beginOffset": 70,
34            "text": "Congestive heart failure"
35          }
36        }
37      ],
38      "status": "CURRENT",
39      "value": "42343007"
40    },
41    {
42      "codingSystem": "SNOMED",
43      "evidence": [
44        {
45          "certainty": "POSITIVE",
46          "status": "HISTORY",
47          "textSpan": {
48            "beginOffset": 136,
49            "text": "seizures"
50          }
51        }
52      ],
53      "status": "HISTORY",
54      "value": "91175000"
55    },
56    {
57      "codingSystem": "SNOMED",
58      "evidence": [
59        {
60          "certainty": "POSITIVE",
61          "status": "CURRENT",
62          "textSpan": {
63            "beginOffset": 148,
64            "text": "Diabetic neuropathy"
65          }
66        }
67      ],
68      "status": "CURRENT",
69      "value": "230572002"
70    },
71    {
72      "codingSystem": "SNOMED",
73      "evidence": [
74        {
75          "certainty": "POSITIVE",
76          "status": "CURRENT",
77          "textSpan": {
78            "beginOffset": 171,
79            "text": "Anxiety"
80          }
81        }
82      ],
83      "status": "CURRENT",
84      "value": "48694002"
85    },
86    {
87      "codingSystem": "SNOMED",
88      "evidence": [
89        {
90          "certainty": "POSITIVE",
91          "status": "CURRENT",
92          "textSpan": {
93            "beginOffset": 182,
94            "text": "Obstructive sleep apnea"
95          }
96        }
97      ],
98      "status": "CURRENT",
99      "value": "78275009"
100    }
101  ],
102  "requestId": 264,
103  "status": "COMPLETED"
104}
    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 CodeHTTP StatusResponse Body
    400Bad Request{ "error": "The request was unacceptable, often due to missing a required parameter." }
    401Unauthorized{ "error": "No valid API key provided." }
    402Token Expired{ "error": "Token expired. Please contact administrator" }
    403Forbidden{ "error": "The API key doesn't have permissions to perform the request." }
    429Trial Quota Excceded{ "error": "Trial quota for API calls exceeded. Please upgrade your plan or try again later." }
    500Internal 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}