ROOK
Roadmap
TryRook
Changelog
←
Back to changelog
Powered by Canny

new

Lab Data: turn your user’s lab reports into structured biomarker data

Lab Data is a new ROOK Connect feature.
It turns the laboratory reports your users already have into structured biomarker data, delivered to your Data Webhook in ROOK JSON or FHIR R4.
Why do lab results matter in a health product?
Before this release, lab results lived inside a PDF or a photo. Teams that wanted them in their product had to ask users to type values by hand, or build and maintain their own document processing for every lab format. Lab Data delivers those results as structured data, and uses the same
user_id
as the rest of your ROOK integration, so you can correlate lab results with the wearable data of the same user.
What does Lab Data do?
During processing, ROOK:
  • Extracts biomarkers from the document.
  • Identifies the clinical panels included in the report.
  • Normalizes biomarker names, units and values.
  • Maps each supported biomarker to its LOINC code.
  • Validates the consistency of each biomarker.
  • Generates a structured response in ROOK JSON or FHIR R4.
Which panels and biomarkers are supported?
Lab Data supports 46 biomarkers across 5 panels:
  • Complete Blood Count (CBC): 21 biomarkers, including white and red blood cell counts, hemoglobin, hematocrit, platelets and the white cell differential.
  • Comprehensive Metabolic Panel (CMP): 14 biomarkers, including glucose, creatinine, eGFR, electrolytes and liver enzymes.
  • Lipid Panel: 5 biomarkers: total cholesterol, LDL, HDL, non-HDL cholesterol and triglycerides.
  • Thyroid Panel: 5 biomarkers: TSH, Free T4, Free T3, Total T4 and Total T3.
  • HbA1c: glycated hemoglobin.
Each biomarker is delivered in its canonical unit, regardless of the unit printed on the document.
Which documents can I submit?
Lab Data accepts three file formats:
  • PDF: digital reports issued by the laboratory and scanned paper reports. Multi-page reports are supported.
  • JPEG: photos of a paper report taken with a phone camera.
  • PNG: screenshots of a report shown in a laboratory portal or app.
The maximum file size is 10 MB, and the document must include a visible sample collection date and time.
What do I receive?
ROOK processes each document asynchronously and sends the result to your Data Webhook as a
lab_result_event
. In ROOK JSON (the default),
laboratory_data
contains metadata,
panels_array
and
rejected_biomarkers_array
. In FHIR R4, it contains metadata and clinical_ready, an HL7 FHIR R4 Bundle. FHIR R4 output requires the Clinical Ready add-on.
Every biomarker includes its LOINC code, its value, its unit and the reference range printed on the document.
How do I enable Lab Data?
  1. Activate Lab Data from the ROOK Portal: go to Products → ROOK Connect and turn on Lab Data. You can also contact the ROOK support team or your account manager.
To receive results in FHIR R4, activate FHIR R4 output from the ROOK Portal or contact the ROOK support team. FHIR R4 output requires the Clinical Ready add-on; without it, Lab Data delivers results in ROOK JSON
  1. Make sure your Data Webhook is configured and routes
    data_structure
    :
    "lab_result_event"
    .
  2. Submit laboratory documents from your backend to the Lab Data endpoint, and store the
    document_id
    returned for each submission.
Lab Data FAQ
1. What problem does Lab Data solve?
Lab Data lets you add laboratory results to your product without asking users to enter values manually, and without building and maintaining your own document processing infrastructure.
2. Which panels and biomarkers does Lab Data support?
Lab Data supports 46 biomarkers across 5 panels: Complete Blood Count (CBC), Comprehensive Metabolic Panel (CMP), Lipid Panel, Thyroid Panel and HbA1c. The complete list, with each LOINC code and canonical unit, is in the Lab Data documentation.
3. Which file formats can I submit?
PDF, JPEG and PNG, up to 10 MB. Other formats, such as HEIC photos, WebP or GIF images, TIFF scans and Word documents, are rejected with 400 Bad Request. Convert them to PDF, JPEG or PNG before submitting.
4. How does ROOK identify the file type?
From the file content, not from its extension or the
Content-Type
of the form part. A PDF renamed to
.jpg
is processed as a PDF, and a file with a
.pdf
extension whose content is not a PDF is rejected.
5. Can I submit a multi-page report with several images?
Each request contains one file, and each image becomes one page. If a report spans several pages, submit it as a single PDF. Images of different pages submitted in separate requests are processed as separate documents.
6. Why is the sample collection date and time required?
Lab Data needs the sample collection date and time to process the document. If either is missing or cannot be read, processing fails and no Data Webhook is sent.
7. How is the time zone of the results determined?
ROOK uses the time zone identified in the document first, then the value you send in the
timezone
field. If neither is available, timestamps are returned without time zone information. The
timezone
value must be an ISO-8601 UTC offset, from
-14:00
to
+14:00
, or
Z
for UTC.
8. What happens to biomarkers that are not supported?
Biomarkers that appear in the document but are not among the 46 supported biomarkers are reported in
rejected_biomarkers_array
with the reason
unsupported_biomarker.
9. Is there an endpoint to check the processing status?
No. All results are delivered automatically to your Data Webhook. Store the
document_id
returned when you submit a document: the same value arrives in the result as
laboratory_data.metadata.document_id_string.
10. Why didn't I receive a Data Webhook after a 200 OK response?
The two most common causes are a duplicate file or a missing or unreadable sample collection date and time. A document is a duplicate when your organization submits a file with exactly the same content as a previous submission, even for a different
user_id
. If you need help, contact ROOK Support with the
document_id.
11. Do ROOK JSON and FHIR R4 include the same information?
Both formats share the same top-level fields and metadata.
confidence_float, plausibility_flag
,
value_corrected_bool
and
original_value_float
are included in ROOK JSON but not in the FHIR R4 output.
12. Can I call Lab Data from a web browser or a mobile app?
No. Lab Data uses your
client_uuid
and
secret_key
, which grant access to your ROOK integration. Submit documents from your backend so the credentials are never exposed to end users.
13. Is Lab Data activated in all environments at once?
No. Sandbox and Production are activated separately. Activation in Sandbox does not activate Production. FHIR R4 output requires the Clinical Ready add-on.
14. Does Lab Data interpret results or provide medical advice?
No. Lab Data structures and standardizes what the laboratory report says. status_string compares each value with the reference range printed on the document. Lab Data does not diagnose conditions or recommend treatment, and it does not replace the judgment of a qualified professional.
Additional resources
Technical documentation: Lab Data
Knowledge Base: