Skip to main content

What do Lab Data API results look like in ROOK JSON and FHIR R4?

See the complete reference for a Lab Data API result: every field of the ROOK JSON payload, the FHIR R4 bundle structure, and complete examples in both formats.

Written by Paola Malo Molina

This article is the complete reference for the Data Webhook payload that Lab Data API sends for each processed document (data_structure: "lab_result_event"). Use it to build and test the handler that receives Lab Data API results. For how to submit documents, see the Lab Data documentation.

Example data only Every identifier, laboratory name, and value in this article is fictional. Your payloads contain your own client_uuid, user_id, and document_id.


Example request

Submit the document from your backend as multipart/form-data, with the file and timezone fields. The timezone value is an ISO-8601 UTC offset, from -14:00 to +14:00, or Z for UTC. This example uses the Sandbox base URL (https://api.lab.rook-connect.review). In Production, use https://api.lab.rook-connect.com.

curl -X POST \
"https://api.lab.rook-connect.review/client_uuid/$ROOK_CLIENT_UUID/user_id/$USER_ID" \
-u "$ROOK_CLIENT_UUID:$ROOK_SECRET_KEY" \
-F "file=@/path/to/laboratory_result.pdf" \
-F "timezone=-05:00"

The -u option builds the Authorization: Basic header from your client_uuid and secret_key. Never submit documents from a web browser or a mobile application, where the credentials would be exposed to end users.
​

If the request is valid, the endpoint returns 200 OK:
​

{
"document_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "received"
}

Store the document_id. The same value arrives in the Data Webhook as laboratory_data.metadata.document_id_string, and in every notification about the document.
​
To declare up to 1,000 documents in a single API call and upload each file separately, use batch upload. Results from batch uploads arrive at the same Data Webhook, in the same format. For the step-by-step guide, see the Lab Data API documentation.

Receiving the result

Lab Data API results arrive at your Data Webhook with the same HMAC validation and retries as the rest of your Data Webhooks. Validate the X-ROOK-HASH header, respond with a 2xx status as soon as you receive the payload, and then process it asynchronously.
​

When a document ends without a result, no Data Webhook is sent. Lab Data API sends a notification to your Notification Webhook instead, with the document_id and a message that says what to do. See Why didn't my Lab Data API result arrive?
​

The result arrives in one of two formats, depending on how Lab Data API is activated for your organization:

ROOK JSON (default)

FHIR R4 (requires Clinical Ready)

Structure

ROOK normalized JSON

HL7 FHIR R4 Bundle of type collection

laboratory_data contains

metadata, panels_array, rejected_biomarkers_array

metadata, clinical_ready

Rejected biomarkers

rejected_biomarkers_array

Observation resources with status: "cancelled"

*FHIR R4 output for Lab Data API requires the Clinical Ready add-on. Activate it from your ROOK Portal or through the ROOK Support team or your account manager.
​
Both formats share the same top-level fields:

Field

Type

Description

client_uuid

string

Your ROOK client identifier.

user_id

string

The user_id you sent in the request.

version

integer

Version of the event envelope. Current value: 2.

document_version

integer

Version of the lab_result_event structure. Current value: 1.

data_structure

string

Always lab_result_event. Use it to route Lab Data API results in your webhook handler.

laboratory_data

object

The processed laboratory result. Its content depends on the format.

ROOK JSON reference

`laboratory_data.metadata`

Field

Type

Description

datetime_string

string

Sample collection date and time as printed on the document, in ISO 8601 format. Includes the UTC offset when it is available: ROOK uses the time zone identified in the document first, then the timezone value you sent (in a batch upload, the time zone declared for each document). If neither is available, the value has no UTC offset.

document_id_string

string

The document_id returned when the document was submitted.

user_id_string

string

The user_id associated with the document.

performing_lab_string

string or null

Name and location of the laboratory that performed the analysis, when it appears in the document.

sources_of_data_array

array of strings

Laboratory providers identified in the document.

is_fasting_bool

boolean or null

Whether the sample was taken while fasting, when the document states it.

`panels_array`

One entry per supported panel identified in the document. A single document can contain several panels.

Field

Type

Description

panel_name_string

string

Name of the panel, for example Complete Blood Count.

panel_code_string

string

Short panel code: CBC, CMP, LIPID, THYROID, HBA1C, VITD, IRON, FERRITIN, CRP, HSCRP, or ESR.

panel_loinc_code_string

string

LOINC code of the panel.

biomarkers_array

array

Biomarkers of this panel that passed every validation.

`biomakers_array`

Field

Type

Description

biomarker_name_string

string

Name of the biomarker.

loinc_code_string

string

LOINC code of the biomarker. See Which biomarkers does Lab Data API support?

value_float

number

Result value, expressed in the canonical unit.

unit_string

string

Unit of value_float. Always equal to canonical_unit_string.

canonical_unit_string

string

Canonical unit of the biomarker.

reference_range_low_float

number or null

Lower limit of the reference range printed on the document, converted to the canonical unit.

reference_range_high_float

number or null

Upper limit of the reference range printed on the document, converted to the canonical unit.

reference_range_unit_string

string or null

Unit of the reference range.

status_string

string

Comparison of the value with the reference range printed on the document: normal, low, high, critical_low, or critical_high. It is not a diagnosis.

confidence_float

number

Extraction confidence, from 0.0 to 1.0. Biomarkers below the minimum confidence required by ROOK are moved to rejected_biomarkers_array.

plausibility_flag

boolean

true when ROOK considers the value doubtful: it crosses a plausibility threshold, a ratio between related biomarkers is unusual (for example BUN/Creatinine or Free T3/Free T4), or a CBC differential percentage and its absolute value do not add up. The value is always delivered as printed on the document, and the flag can appear on correct values. ROOK recommends reviewing these values before using them in clinical decisions

`rejected_biomarkers_array`
​

Biomarkers found in the document that did not pass validation. The array is always present, and it is empty when every biomarker passed.

Field

Type

Description

biomarker_name_string

string

Name of the biomarker as it appears in the document.

loinc_code_string

string or null

LOINC code, when it could be identified.

extracted_value_string

string

Value as extracted from the document.

extracted_unit_string

string

Unit as extracted from the document.

reason_string

string

Reason for the rejection. See the following table.

confidence_float

number

Extraction confidence at the time of the rejection.

reason_string

Meaning

low_confidence

The value could not be extracted with the minimum confidence required by ROOK, or its structure was not valid.

unsupported_biomarker

The biomarker is not part of the supported biomarkers.

unknown_unit

The unit printed on the document could not be converted to the canonical unit.

implausible_value

The value falls outside physiological limits.

not_mapped

The result could not be mapped to a LOINC code, for example qualitative results or non-standard markers.

The following document contains two panels (CBC and CMP) with accepted biomarkers, and one biomarker in rejected_biomarkers_array.
​

  "client_uuid": "c2f4ce3b-8e6d-4b5f-9a3e-1d2c3b4a5f6e",
"user_id": "user_1234",
"version": 2,
"document_version": 1,
"data_structure": "lab_result_event",
"laboratory_data": {
"metadata": {
"datetime_string": "2026-03-15T08:30:00-05:00",
"performing_lab_string": "Example Clinical Laboratory - North Branch",
"is_fasting_bool": true,
"user_id_string": "user_1234",
"document_id_string": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sources_of_data_array": ["Example Clinical Laboratory - North Branch"]
},
"panels_array": [
{
"panel_name_string": "Complete Blood Count",
"panel_code_string": "CBC",
"panel_loinc_code_string": "58410-2",
"biomarkers_array": [
{
"biomarker_name_string": "Hemoglobin",
"loinc_code_string": "718-7",
"value_float": 14.5,
"unit_string": "g/dL",
"canonical_unit_string": "g/dL",
"reference_range_low_float": 12.0,
"reference_range_high_float": 17.5,
"reference_range_unit_string": "g/dL",
"status_string": "normal",
"confidence_float": 0.98,
"plausibility_flag": false
},
{
"biomarker_name_string": "White Blood Cell Count",
"loinc_code_string": "6690-2",
"value_float": 5.05,
"unit_string": "10^3/uL",
"canonical_unit_string": "10^3/uL",
"reference_range_low_float": 4.5,
"reference_range_high_float": 11.0,
"reference_range_unit_string": "10^3/uL",
"status_string": "normal",
"confidence_float": 0.97,
"plausibility_flag": false
}
]
},
{
"panel_name_string": "Comprehensive Metabolic Panel",
"panel_code_string": "CMP",
"panel_loinc_code_string": "24323-8",
"biomarkers_array": [
{
"biomarker_name_string": "Blood Urea Nitrogen",
"loinc_code_string": "3094-0",
"value_float": 15.7,
"unit_string": "mg/dL",
"canonical_unit_string": "mg/dL",
"reference_range_low_float": 7.0,
"reference_range_high_float": 20.0,
"reference_range_unit_string": "mg/dL",
"status_string": "normal",
"confidence_float": 0.95,
"plausibility_flag": false,

}
]
}
],
"rejected_biomarkers_array": [
{
"biomarker_name_string": "Vitamin B12",
"loinc_code_string": "2132-9",
"extracted_value_string": "250.0",
"extracted_unit_string": "pg/mL",
"reason_string": "unsupported_biomarker",
"confidence_float": 0.93
}
]
}
}


​What to notice in this example

  • metadata carries the sample collection date and time with its UTC offset, the performing laboratory, and the document_id_string returned by the request.
    ​

  • panels_array groups accepted biomarkers by panel. Each biomarker has its LOINC code and its value in the canonical unit.
    ​

  • Every biomarker in this example has plausibility_flag: false. When it is true, the value is still delivered exactly as printed on the document, but ROOK considers it doubtful, for example because a ratio between related biomarkers is unusual. ROOK never changes the value, and the flag can appear on correct values, so review those values before using them in clinical decisions.
    ​

  • Vitamin B12 appears in rejected_biomarkers_array with unsupported_biomarker, because it is not one of the supported biomarkers.

FHIR R4 reference

In FHIR R4 mode, laboratory_data keeps metadata and replaces panels_array and rejected_biomarkers_array with clinical_ready, an HL7 FHIR R4 Bundle of type collection.

Resource

Cardinality

Content

Patient

1

The user_id as identifier, with system urn:rook:user-id.

Practitioner

1

The ordering provider’s identifier. The provider’s name is not delivered in the current Lab Data API output.

Organization

1

The laboratory that performed the analysis, from performing_lab_string.

Observation (status: "final")

One per accepted biomarker

LOINC code, value, unit, reference range, and interpretation.

DiagnosticReport

One per panel

Panel LOINC code, sample collection date and time, and references to the panel's Observation resources.

Observation (status: "cancelled")

One per rejected biomarker

Biomarker name, with the rejection reason and extracted value in note.

Each accepted biomarker maps to an Observation as follows:

ROOK JSON field

FHIR R4 field

loinc_code_string

code.coding[0].code (system http://loinc.org)

biomarker_name_string

code.coding[0].display and code.text

value_float

valueQuantity.value

canonical_unit_string

valueQuantity.unit, and valueQuantity.code in UCUM notation (for example, 10^3/uLbecomes 10*3/uL)

reference_range_low_float / reference_range_high_float

referenceRange[0].low / referenceRange[0].high

status_string

interpretation[0].coding[0]: N (normal), L (low), H (high), LL (critical low), HH (critical high)

confidence_float, plausibility_flag, are not included in the FHIR R4 output.

Example FHIR R4 payload

This example is an excerpt: it shows the shared resources, one accepted biomarker with its DiagnosticReport, and one rejected biomarker. A real bundle contains one Observation per accepted biomarker and one DiagnosticReport per panel.

{
"client_uuid": "c2f4ce3b-8e6d-4b5f-9a3e-1d2c3b4a5f6e",
"user_id": "user_1234",
"version": 2,
"document_version": 1,
"data_structure": "lab_result_event",
"laboratory_data": {
"metadata": {
"datetime_string": "2026-03-15T08:30:00-05:00",
"performing_lab_string": "Example Clinical Laboratory - North Branch",
"is_fasting_bool": true,
"user_id_string": "user_1234",
"document_id_string": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sources_of_data_array": ["Example Clinical Laboratory - North Branch"]
},
"clinical_ready": {
"resourceType": "Bundle",
"id": "d720e9b8-e108-4f26-b784-30b1382e7be8",
"type": "collection",
"timestamp": "2026-03-15T14:02:11Z",
"entry": [
{
"fullUrl": "urn:uuid:2680a059-6f3c-4c1e-9d0a-5b7e1f3c9a11",
"resource": {
"resourceType": "Patient",
"id": "2680a059-6f3c-4c1e-9d0a-5b7e1f3c9a11",
"identifier": [
{ "system": "urn:rook:user-id", "value": "user_1234" }
]
}
},
{
"fullUrl": "urn:uuid:7b1d2c44-0a9e-4f7b-8c61-2e5d9f0a3b22",
"resource": {
"resourceType": "Practitioner",
"id": "7b1d2c44-0a9e-4f7b-8c61-2e5d9f0a3b22"
}
},
{
"fullUrl": "urn:uuid:c93e5a10-4d2b-4b8f-a7e6-9f1c0d2e4b33",
"resource": {
"resourceType": "Organization",
"id": "c93e5a10-4d2b-4b8f-a7e6-9f1c0d2e4b33",
"name": "Example Clinical Laboratory - North Branch"
}
},
{
"fullUrl": "urn:uuid:1bb895f4-8e2a-4d6c-b3f1-7a9e0c5d2f44",
"resource": {
"resourceType": "Observation",
"id": "1bb895f4-8e2a-4d6c-b3f1-7a9e0c5d2f44",
"status": "final",
"code": {
"coding": [
{ "system": "http://loinc.org", "code": "6690-2", "display": "White Blood Cell Count" }
],
"text": "White Blood Cell Count"
},
"subject": { "reference": "urn:uuid:2680a059-6f3c-4c1e-9d0a-5b7e1f3c9a11" },
"valueQuantity": {
"value": 5.05,
"unit": "10^3/uL",
"system": "http://unitsofmeasure.org",
"code": "10*3/uL"
},
"referenceRange": [
{
"low": { "value": 4.5, "unit": "10^3/uL", "system": "http://unitsofmeasure.org", "code": "10*3/uL" },
"high": { "value": 11.0, "unit": "10^3/uL", "system": "http://unitsofmeasure.org", "code": "10*3/uL" }
}
],
"interpretation": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
"code": "N",
"display": "Normal"
}
]
}
]
}
},
{
"fullUrl": "urn:uuid:5e2f8a91-3c7d-4e0b-9a14-6d8b2c1f0e55",
"resource": {
"resourceType": "DiagnosticReport",
"id": "5e2f8a91-3c7d-4e0b-9a14-6d8b2c1f0e55",
"status": "final",
"code": {
"coding": [
{ "system": "http://loinc.org", "code": "58410-2", "display": "Complete Blood Count" },
{ "system": "urn:rook:panel-code", "code": "CBC", "display": "Complete Blood Count" }
],
"text": "Complete Blood Count"
},
"subject": { "reference": "urn:uuid:2680a059-6f3c-4c1e-9d0a-5b7e1f3c9a11" },
"effectiveDateTime": "2026-03-15T08:30:00-05:00",
"performer": [
{ "reference": "urn:uuid:7b1d2c44-0a9e-4f7b-8c61-2e5d9f0a3b22" },
{ "reference": "urn:uuid:c93e5a10-4d2b-4b8f-a7e6-9f1c0d2e4b33" }
],
"result": [
{ "reference": "urn:uuid:1bb895f4-8e2a-4d6c-b3f1-7a9e0c5d2f44" }
]
}
},
{
"fullUrl": "urn:uuid:35489c90-7b1e-4a2d-8f3c-0e9d6a5b4c66",
"resource": {
"resourceType": "Observation",
"id": "35489c90-7b1e-4a2d-8f3c-0e9d6a5b4c66",
"status": "cancelled",
"code": { "text": "Vitamin B12" },
"subject": { "reference": "urn:uuid:2680a059-6f3c-4c1e-9d0a-5b7e1f3c9a11" },
"note": [
{ "text": "Rejected — reason: unsupported_biomarker. Extracted value: 250.0" }
]
}
}
]
}
}
}

Two timestamps appear in the bundle: timestamp is the time ROOK generated the bundle, and DiagnosticReport.effectiveDateTime is the sample collection date and time.

Route by data_structure. Lab Data API FHIR R4 results arrive with data_structure: "lab_result_event", and the bundle is at laboratory_data.clinical_ready. The Clinical Ready add-on uses a different structure (data_structure: "clinical_ready") for wearable summaries. Route both by data_structure.

Did this answer your question?