Overview
Last updated
Was this helpful?
Last updated
Was this helpful?
The Blood Biomarkers API provides a streamlined method for uploading medical reports (e.g., blood tests, urine tests) and receiving parsed biomarker data in a structured JSON format. The API accepts multiple file types (PDF, PNG, JPEG) and returns an immediate HTTP response confirming the upload, while also sending detailed parsed results asynchronously to your configured webhook or other destination.
• Structure your HTTP request using the (make sure to include your actual file instead of the example path provided below)
• Ensure that you include the required headers (dev-id and x-api-key) and set the Content-Type to multipart/form-data.
• Optionally include the reference_id query parameter to associate the report with an existing connection. Alternatively you may use the `upload_id returned in order to reconciliate the blood report internally
• Execute your request using cURL or another HTTP client.
• The API will immediately return a 202 Accepted response with an upload_id and list the uploaded file names.
• Configure your webhook or destination endpoint to receive the asynchronous parsed output.
• Use the field specifications to correctly integrate the data into your system.
• In case of errors (e.g., invalid file formats), the API will return a Problem Details response with fields such as type, title, status, detail, and instance to help you diagnose and resolve issues.
Headers
dev-id
<developer ID>
x-api-key
<API Key>
Content-Type
multipart/form-data
Query parameters
reference_id
string (optional)
Associates the reports with a specific identifier. Allows you to track which user the report belongs to, to reconciliate the event sent to your destination.
Body (form-data)
files
file
Files to upload
Once the report is processed, a structured JSON payload containing the parsed biomarker data is sent to your configured webhook or destination. This payload includes timestamps and an array of test results.
Each result in the results array contains:
• original_name: The exact name as it appears on the report.
• display_name: A human-readable name in proper case.
• type: The test type (e.g., blood, urine).
• biomarker: The biomarker enum value. See below for total list of possible values.
• value: The numerical result value.
• value_bound: An object containing any bounds on the value:
• greater_than: If the value is marked as “greater than” a threshold.
• less_than: If the value is marked as “less than” a threshold.
• display_units: The human-readable format of the units.
• units: A structured object with:
• numerator: The unit in the numerator (e.g., “g”, “mg”).
• denominator: The unit in the denominator (e.g., “dL”, “L”).
• exponent: The power of 10 multiplier (e.g., 3 for thousands).
• reference_ranges: An array of reference range objects, each containing:
• age_lower_bound: Lower age limit (or null if missing).
• age_upper_bound: Upper age limit (or null if missing).
• reference_lower_bound: The lower limit of the reference range.
• reference_upper_bound: The upper limit of the reference range.
• classification: an string enum value between "normal" "abnormal" and "borderline" associated with the meaning of the reference range
• Missing Date: "date": null
• Missing Time: "time": null
• Missing Reference Range Bounds: Missing reference_lower_bound or reference_upper_bound -> set each to null. If only a single one is missing this means the reference range is bounded only in one direction (e.g. <200)
• Missing Age Ranges: Both age_lower_bound and age_upper_bound are null. These are filled only when an age range is provided for the reference range boundary
• Unclear Values: "value": "Not specified" when the value cannot be clearly determined (e.g. the text is unclear/muddled)
• Missing Units: All unit fields are null and "display_units" is "Unknown"
• Bounded Values: If a value is provided as “greater than X”, value_bound.greater_than is set to X and value to null
The units object breaks down the unit representation into:
• numerator: The unit in the numerator (e.g., “g”, “mg”).
• denominator: The unit in the denominator (e.g., “dL”, “L”).
• exponent: The multiplier exponent (e.g., 3 for thousands, 6 for millions. This is in the case of markers which are measured in 10^X units. E.g. white blood cell count, red blood cell count etc are often found in that notation ).
• The webhook payload contains the structured JSON with timestamp and
POST