Overview
Biomarkers API Documentation *BETA*
Overview
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.
How to Use This API
1. Prepare Your Request:
• Structure your HTTP request using the provided cURL example. (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
2. Submit Your Request:
• 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.
3. Process the Asynchronous Response:
• Configure your webhook or destination endpoint to receive the asynchronous parsed output.
• The webhook payload contains the structured JSON with timestamp and detailed biomarker results.
• Use the field specifications to correctly integrate the data into your system.
Ensure you use UTF-8 encoding when parisng the JSON response! non-ASCII symbols may be included in field values
4. Error Handling
• 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.
API Endpoint: Upload Report
POST https://api.tryterra.co/v2/reports/upload
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
Immediate HTTP Response
{
"upload_id": "1ba20c83-9cfa-422a-9a51-eb0a4bf6636d",
"files": [
{
"file_name": "2023-10-05.pdf"
}
]
}cURL example:
curl --location 'https://api.tryterra.co/v2/reports/upload?reference_id=Bob' \
--header 'dev-id: <Dev ID>' \
--header 'x-api-key: <API Key>' \
--form 'files=@"/Users/Terra/Library/blood tests/2023-10-05.pdf"'Asynchronous Webhook Output
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.
{
"date": "2023-05-15",
"time": "09:49",
"results": [
{
"original_name": "Haemoglobin",
"display_name": "Hemoglobin",
"type": "blood",
"biomarker": "hemoglobin_blood",
"value": 14.2,
"value_bound": {
"greater_than": null,
"less_than": null
},
"display_units": "g/dL",
"units": {
"numerator": "g",
"denominator": "dL",
"exponent": 0
},
"reference_ranges": [
{
"age_lower_bound": 3,
"age_upper_bound": 18,
"reference_lower_bound": 4.5,
"reference_upper_bound": 11.0,
"classification": "normal"
}
]
}
]
}Field Specifications
Result Object
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
Handling Missing Data
• 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
Units Structure
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 ).
List of biomarker enums
Last updated
Was this helpful?