Document Type - Lab Result
Document Type - Lab Results. These documents are processed by athenahealth, for example, lab results obtained from a blood draw, fluid specimen, or a biopsy/surgical excision. Lab results are with the laboratory name, the date and time of the specimen collection, analytes and values, growth rate, or observations of tissue samples. Whenever possible, structured analytes should be entered on documents. Analytes are entered by practice users unless they are received via interface. This feature allows the user to retrieve, add or modify information of a specific patient or a specific lab result of a patient. It also provides a facility to retrieve lab results document in HTML. The document content could be images, XML.etc. The Lab Result Changed Subscription feature will allow the user to retrieve, delete, create or modify changes to lab results. The user will need to subscribe. For more information about subscriptions, please refer Changed Data Subscriptions.
Lab Results
Obtained from a blood draw, fluid specimen, or a biopsy/surgical excision, lab results appear in the Results section of a patient’s chart. By default, lab result documents are created in an open status. However, creating lab results in a closed status is encouraged if the practice has already reviewed this data via another mechanism.
Whenever possible, structured analytes should be entered on documents, and clinicalordertype (test type) and clinicalprovider (performing lab/data source) should always be specified.
Note: Subclassification is not available for this document class.
Lab Analytes
API users can add and update lab analyte results through the existing lab result document POST and PUT endpoints for a specified patient. An analyte is a lab result value, such as glucose, HDL cholesterol, and WBC.
The user's application must be the primary source of the lab analytes added through the lab result API. The analytes being uploaded into athenaNet are only a copy of the data available through the user's own application. The user is responsible for contacting/warning a patient’s provider or care team if any analyte result collected from a patient is outside of a reasonable threshold.
Adding Lab Analytes
Using the lab result document endpoint, users can create a lab result document with one or more lab analytes. The lab analyte value in the POST API is a url-encoded JSON structure. Each entry contains items related to an analyte. Example lab analyte value for the POST:
[
{
"analytename" : "HGB A1C",
"units" : "%",
"abnormalflag" : "ABNORMAL",
"referencerange" : "1-10",
"resultstatus" : "Final",
"value" : "5",
"note" : "example note"
},
{
"analytename" : "Alpha-1-Globulin",
"units" : "mg/mol",
"abnormalflag" : "CRITICAL HIGH",
"referencerange" : "0.05-0.09",
"resultstatus" : "Pending",
"value" : "1.5",
"note" : "example note"
}
]
The analytename is required in order to POST a lab analyte. All other fields are optional.
Updating Lab Analytes
Lab analytes associated with lab result documents can be updated through the lab result PUT endpoint. You must first get the labresultid of the lab result. You can get this from the lab result GET API via:
GET /patients/{patientid}/documents/labresult?departmentid={departmentid}
After retrieving the labresultid, you will must then get the analyteid of the analyte that you want to update. The analyteid uniquely identifies that particular analyte result. You can use the analyteid to update the fields associated with that particular analyte result using the document specific lab result GET API via:
GET /patients/{patientid}/documents/labresult/{labresultid}?departmentid={departmentid}
Sample API Response:
[
{
"createddate" : "05\/11\/2016",
"description" : "lab result",
"documentsource" : "INTERFACE",
"labresultid" : "664739",
"lastmodifieddate" : "05\/11\/2016",
"observations" : [
{
"abnormalflag" : "abnormal",
"analyteid" : "872001",
"analytename" : "HGB A1C",
"note" : "example note",
"referencerange" : "1-10",
"resultstatus" : "final",
"units" : "%",
"value" : "5"
}
],
"pages" : [],
"priority" : "2",
"status" : "REVIEW"
}
]
Once you have the analyteid(s), you will must add a ‘“analyteid” : “{analyteid}}’ line to all the entries of the analyte(s) you are updating.
If an entry doesn’t have an analyteid, it will be considered a new analyte instead of an update and added to the lab result document.
Example lab analyte value for the PUT:
[
{
"analytename" : "HGB A1C",
"analyteid" : "123456",
"loinc" : "12773-9",
"units" : "%",
"abnormalflag" : "ABNORMAL",
"referencerange" : "1-10",
"resultstatus" : "Final",
"value" : "12",
"note" : "example note"
},
{
"analytename" : "ACTH, Plasma",
"units" : "mg/mol",
"abnormalflag" : "NORMAL",
}
]
NOTE: The above example would update the HGB A1C analyte since the analyteid was provided and add the ACTH, Plasma analyte to the lab result since the analyteid was NOT provided.
Endpoints
-
Primary
PUT
- Subscription
Retrieves action note information of a specific lab document
Input Parameters
Expand allOutput Parameters
Expand allCreates an action note for a specific Lab Result document
Input Parameters
Expand all❙ Request Body
Expand allOutput Parameters
Expand allRetrieves an interpretation document record of a specific patient
Input Parameters
Expand all❙ required
Output Parameters
Expand allRetrieves a list of lab result document information of a specific patient
Input Parameters
Expand all❙ required
Output Parameters
Expand allCreates a lab result document record of a specific patient
Input Parameters
Expand all❙ Request Body
Expand allRetrieves a specific lab result document information
Input Parameters
Expand allOutput Parameters
Expand allModifies a specific lab result document information
Input Parameters
Expand all❙ Request Body
Expand allDeletes the record of a specified lab result document
Input Parameters
Expand allRetrieves a specific page from the specific lab result document of the patient
Input Parameters
Expand allOutput Parameters
Expand allReturns a success message pertaining to the update.
Input Parameters
Expand all❙ Request Body
Expand allAdvances a lab result to a closed status. Note: This endpoint may rely on specific settings to be enabled in athenaNet Production to function properly that are not required in other environments. Please see <a href="https://docs.athenahealth.com/api/resources/best-practices-and-troubles… Rollout of APIs</a> for more information if you are experiencing issues.
Input Parameters
Expand allRetrieve list of all events that can be input for this subscription.
Input Parameters
Expand all❙ required
Subscribes for changed lab results events
Input Parameters
Expand all❙ Request Body
Expand allOutput Parameters
Expand allRetrieves list of events applicable for lab results changes
Input Parameters
Expand all❙ required
Retrieves list of records of modified lab results of patient
Input Parameters
Expand all❙ required
Output Parameters
Expand allDeletes a specific event which is no longer required