Blood Result Upload
Submit OCR, FHIR, or HL7 blood result files for asynchronous BRU processing, track status, and receive terminal updates when published results are available.
Blood Result Upload
Blood Result Upload, or BRU, lets you submit one or more blood result source files to InsideTracker for asynchronous processing. Use it to upload supported files, submit them for processing, and track when published blood results are available for downstream outputs such as recommendations, category scores, and Inner Age.
Send one supported source file at a time for a linked customer record.
Group uploaded files into an asynchronous BRU processing job.
Track processing so your application knows when published blood results are available.
Where This Fits
Use BRU when your application or User has files containing blood results.
BRU is different from lab ordering. Use Lab Connect when you need to order a new Quest or Mobile Blood Draw test. Use Add Blood Result when your system already has discrete marker values and needs to submit them directly through the structured blood result API.
What You Need
Before implementing BRU, make sure you have:
- A linked InsideTracker customer record for your User.
- A customer-level token.
- The
bru.uploadscope to upload files and submit a process. - The
bru.statusscope to retrieve process status. - One or more supported blood result source files.
- A way to store
uploadedFileIdandprocessIdvalues in your system. - A way to check processing status after process submission.
Supported Upload Types
BRU uses one route model for all supported source files. The backend processing type differs by file format.
| Processing type | Accepted source | Accepted MIME types | Size limit |
|---|---|---|---|
| Document/OCR | application/pdf | Smaller than 50 MB | |
| Document/OCR | GIF, JPEG, PNG, or WebP image | image/gif, image/jpeg, image/png, image/webp | Smaller than 50 MB |
| FHIR | .ndjson or .jsonl | application/json, application/ndjson, application/x-ndjson, text/plain | Smaller than 50 MB |
| HL7 | .hl7 | application/hl7, application/hl7-v2, text/plain | Smaller than 10 MB |
InsideTracker performs virus scanning on uploaded files. Infected files are rejected. Unsupported file types return 400 Bad Request.
How BRU Works
1. Upload Each File
Upload each source file separately with multipart/form-data:
POST /bru/customer/v1/files
Content-Type: multipart/form-data
Authorization: Bearer {customer_token}Include one required multipart field:
| Field | Type | Description |
|---|---|---|
file | string <binary> | Single supported BRU source file. |
Successful response:
{
"uploadedFileId": "97395c45-160a-44e6-a6db-f76570e12f8f"
}| Field | Description |
|---|---|
uploadedFileId | Temporary file identifier required for BRU process submission. |
Additional upload behavior:
- Store every returned
uploadedFileIduntil process submission. - Uploads are rate limited to 14 files per customer per 300 seconds.
- Uploaded files expire after 24 hours if they are not submitted in a BRU process.
2. Submit The BRU Process
Submit a process with the full list of file IDs returned by the upload step:
POST /bru/customer/v1/processes
Content-Type: application/json
Authorization: Bearer {customer_token}{
"uploadedFileIds": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}| Field | Description |
|---|---|
uploadedFileIds | List of temporary file identifiers returned by the upload step. Must include at least one file. |
The process submission returns 202 Accepted with a processId and the current process state. Store the returned processId so you can track the submission.
A single BRU process must contain at least one file, and every file in that process must use the same processing type. Do not mix Document/OCR, FHIR, and HL7 files in the same process.
Process submission and status responses include fields such as:
| Field | Description |
|---|---|
processId | Identifier for the asynchronous BRU process. |
autoPublishResult | Indicates whether the process is configured to publish results automatically. |
validationMode | Validation mode for the process, such as AUTO. |
status | Current process status, such as DOCUMENT_UPLOADED after submission. |
bloodResults | Published blood result legacy IDs when available. |
createdAt | Process creation timestamp. |
updatedAt | Most recent process update timestamp. |
3. Track Processing
Use the process status endpoint when you need the latest process state:
GET /bru/customer/v1/processes/{processId}
Authorization: Bearer {customer_token}The response returns the current process state using the same process fields described above. When a process is in a terminal state, the response may include bloodResults with published blood result legacy IDs.
File Type Guidance
Use the tab for the source format you are submitting.
Use OCR when a User has existing blood result documents, such as lab PDFs, scans, screenshots, or photos of printed reports. InsideTracker processes those files asynchronously and converts extracted marker values into structured blood biomarker data when possible.
Source expectations
- Supported file types for OCR are PDF, GIF, JPEG, PNG, and WebP.
- Each file must be smaller than 50 MB.
- Clear, complete, readable documents are more likely to process successfully than blurry, cropped, or partial images.
- OCR extraction is not guaranteed. Set expectations that the file is being processed and converted into structured health data when possible.
Use FHIR when the source data is represented as FHIR R4 Observation resources in NDJSON form. Each non-empty line must contain one FHIR JSON resource.
Source expectations
- Accepted files use
.ndjsonor.jsonl. - Every non-empty line must be a valid FHIR R4
Observation. - JSON arrays and other FHIR resource types are not supported.
Observation.codemust include a usableCodingwith bothsystemandcode.Observation.value[x]must be represented asvalueQuantity.valueQuantitymust includevalueandunit.- LOINC coding with system
http://loinc.orgis preferred when available. - The observation date is read from
effectiveDateTime, one form of FHIR'seffective[x]element, withissuedused as a fallback. - A parseable date is required for successful automatic mapping and publication.
- Reference ranges are extracted from
referenceRangewhen present.
Preparation guidance
Validate that each line contains one complete Observation before upload. If your source system exports bundles, arrays, panels with component values, or non-Observation resources, transform those records into supported Observation NDJSON before submitting them through BRU.
Use HL7 when the source data is a laboratory result message in HL7 v2 ORU^R01 form.
Source expectations
- Accepted files use
.hl7. - Each file must contain exactly one HL7 v2 message.
- The file must begin with
MSH|; a UTF-8 BOM and leading whitespace are tolerated. - The message type must be
ORU^R01. - Files containing more than one
MSHmessage are rejected. - Observations are read from
OBXsegments. - Supported OBX value types are
NM,SN,ST, andTX. - Every
OBXmust include a usable observation code, value, and unit. - Only observation values that normalize to a number can be automatically mapped and published.
- The observation date is read from the OBX observation datetime, falling back to the current OBR observation or specimen datetime.
- A resolved date from OBX or the current OBR is required for successful automatic mapping and publication.
- Each file must be smaller than 10 MB.
Preparation guidance
Validate that each file contains one ORU^R01 message and that every result-bearing OBX segment has the code, value, unit, and date information needed for automatic mapping.
User Experience States
BRU processing is asynchronous for all supported file types. In your application, use simple states that reflect the file submission and processing lifecycle.
| State | Meaning |
|---|---|
| Not started | User has not uploaded or selected files. |
| Uploading | One or more files are being submitted. |
| Processing | Files were accepted and are being processed by InsideTracker. |
| Results available | Processing published blood results successfully. |
| Action needed | Upload failed, the file could not be processed, or no published result was produced. |
Process Statuses
BRU processes may return these statuses:
| Status | Meaning |
|---|---|
DOCUMENT_UPLOADED | The process was accepted and its uploaded files are ready for processing. |
DOCUMENT_PARSED | The source files were parsed. |
DOCUMENT_MAPPED | Parsed markers were mapped. Processing will next either publish the results or finish without publication. |
PUBLISHED | Processing finished and blood results were published through the existing Blood API. |
COMPLETE | Processing finished without publishing blood results. |
Completion Handling
Use the process response or configured BRU completion events to correlate the completed process back to the User and submission in your system.
| Field | Use |
|---|---|
extId | Maps the event back to your User. |
processId | Matches the event to the BRU process you submitted. |
status | Indicates the terminal process state. |
bloodResults | Contains published blood result legacy IDs when results are available. |
validationMode | Indicates the validation mode used for the process. |
autoPublishResult | Indicates whether the process was configured to publish automatically. |
Terminal states:
| Status | Meaning | Application action |
|---|---|---|
PUBLISHED | Processing completed successfully and published blood results are available through the existing Blood API. | Mark the submission complete and retrieve or refresh downstream blood result/output data. |
COMPLETE | Processing completed, but no published blood result was produced. | Do not show new results. Route the submission through your support or exception-handling workflow. |
Implementation Checklist
Before building
- You have a linked customer record and customer-level token for the User.
- Your token includes
bru.uploadandbru.status. - You accept only supported Document/OCR, FHIR, or HL7 source files.
- You upload each file separately and store every returned
uploadedFileId. - You submit all relevant
uploadedFileIdsin one BRU process. - You do not mix Document/OCR, FHIR, and HL7 files in the same process.
- You store the returned
processId. - You can poll
GET /bru/customer/v1/processes/{processId}and handle configured BRU completion events if enabled. - You handle
PUBLISHEDas the success path for published blood results. - You have an exception path if processing completes without published results.
Testing Checklist
- Upload succeeds for a supported OCR document or image.
- Upload succeeds for a valid FHIR R4 Observation NDJSON file.
- Upload succeeds for a valid HL7 v2 ORU^R01
.hl7file. - Multiple files of the same processing type can be submitted through one BRU process, with each file uploaded separately.
- Mixed Document/OCR, FHIR, and HL7 files are not submitted in the same process.
- Oversized or unsupported files produce a clear User-facing error.
- Completion status updates the correct User.
- Duplicate or repeated uploads do not create confusing User-facing results.
- Support can trace a User issue back to the submitted file and BRU
processId.
Related Topics
- Webhooks
- Add Blood Result
- Lab Connect
- Adding Profile Data
Updated about 2 months ago