Ordering Labs via API
API customers of Akute have the ability to order labs automatically through your own systems via our APIs. This allows you to easily automate commonly order labs without needing to manually go into the chart and go through the entire ordering process for every patient that needs the same labs.
From the labs perspective, this is no different than if you ordered via our UI. The results will still come in electronically to Akute and you can set up webhooks to listen for those results in the developer tab.
Customers must be on certain plans to have API access. If you do not currently have API access or do not know if your plan supports it and would like to utilize these features, please contact us at support@akutehealth.com.
Here's how this process works:
Search for lab procedure options (e.g. cbc, cmp, etc.):
- GET /v1/procedures
- parameters:
{
query: {search_term - can be the name of a test or the code of a test if you already know the codes},
performer_organization_id: {id for the organization performing the test. e.g. labcorp or quest. We'll provide these IDs to you},
limit: {number of results to return - used for pagination},
offset: {number of results to skip - used for pagination},
}
performer_organization_id:- Labcorp: use f-e20f61500ba128d340068ff6 in staging. This is a Labcorp test organization.
- Quest: Not available for electronic lab ordering in staging.
- TestingLab Facility: f-4f0235627ac2d59b49e5575c. Good for use in staging as orders to this lab also return results.
An array of objects. Each object is a procedure that will need to be included in your order API call.
e.g.
[ {
"system": "urn:uuid:f:e90f6150fc112badf159be4f",
"code": "19115",
"display": "COMPREHENSIVE METABOLIC PANEL W/O ALT AND eGFR"
} ]
- use case:
When you order the same panel of labs each time, then you can search for the labs you usually order, save them in your db/code, and then just re-use those same arrays in the POST orders api going forward. Meaning, you won't need to search for the procedures each time if you're always ordering the same panels.
- POST /v1/orders
- body:
{"patient_id": {akute_patient_id},
"external_patient_id": {your patient ID if it's been saved to a patient's profile. Can be used in-lieu of patient_id. If patient_id is provided, our system will ignore external_patient_id},
"procedures": {array of procedure objects obtained from step 1 above},
"billing_type": {enum of ["third_party", "patient", "client"] meaning, bill insurance (third party, bill patient directly, or lab bills you (client)},
"delivery_option": {"electronic" - we only support "electronic" as of now for API ordering},
"ordering_user_id": {user_id of ordering clinician with an NPI. Can be obtained via our GET users API. Ask Akute support to set up a test clinician in staging for your account.},
"performer_organization_id": {same performer_organization_id as step 1},
"account_number": {the account number your company has with the lab.},
"diagnoses": {array of ICD10 diagnosis codes to add to order. e.g. ["R05.1", "E11.65"]}
}
- response:
If error:
400+ code
{ error: String }
If success:
201 code
{ id: String }
If pending (this means your order request is still being sent & verified with the lab facility. It may still succeed or fail being sent):
202 code
{ request_id: String } -
Set up Order Requests & Order Webhooks
In the Developer settings, set up webhooks so you can receive updates when the status changes, and thus you can take action if an order request fails. Usually, orders fail due to the following reasons:
a) Connections to the labs are currently down and order will need to be re-requested
b) Lab order needs to be split into separate orders. This can be due to the list of procedures including tests that are performed with different specimen types (e.g. blood, urine, biopsy, etc.). Orders with different specimen types need to be ordered separately.
c) Various other reasons. This will be included in the error response -
GET /v1/orders/requests/:id
Can be used to get order request status updates, in case you missed the webhook update or need a real-time update
The response will match the response of POST /v1/orders. - GET /v1/orders/:id
Can be used to get order response, in case you missed the webhook update or need a real-time update
This can include fields such as document_id, which can be used to get PDF of report via GET /v1/documents/:id. -
GET /v1/diagnosticreport/:id?
Will include metadata about a lab result report, including issued timestamp, patient, if abnormal results are contained,
- parameters:
{
patient_id,
external_patient_id,
start_date_range,
lab_reference_id,
order_id,
limit: { used for pagination - min(1).max(100) },
offset: { used for pagination - min(0) }
}
- response:
Will include metadata about a lab result report, including:
{
issued: {timestamp},
patient_id
interpretation: { if abnormal results are contained },
document_id: { used to get PDF of report via GET /v1/documents/:id },
status: { preliminary, final, amended, etc },
etc.
} - GET /v1/observations/:id?
Includes individual results from diagnostic report
- parameters:
{
category: { laboratory },
patient_id: { patient_id },
external_patient_id: { external_patient_id },
diagnostic_report_id: { diagnostic_report_id },
}
- response:
Includes data about the individual lab result such as range values, interpretation, etc.
Watch for critical results, which can be determined by the following fields:
{
interpretation: "Above critical high normal",
interpretation_code: "HH",
interpretation_code_system: "http://hl7.org/fhir/v2/0078",
}
Specifically, "HH" and "LL" for interpretation_code mean critical results. Rate Limiting
Akute API usage, specifically wrt lab ordering APIs listed here, are expected to be limited to 5 concurrent API requests by any single tenant/client.
Please let us know if you have any questions about this! This is a relatively complex API call and we want to be as helpful as possible with it. Happy to set up a call to walk through this if that's more helpful.