This section describes a basic flow to retrieve the results of a given test. The BioTests API offers a few variants, be sure to refer to the full API Reference.

Retrieving the test id

In order to retrieve the results of a particular test, you will generally need the test ID. This is different from the kit ID or order number. The test ID is shared with you via a webhook notification (it is included in all notifications starting at the LAB_ACCESSIONED step). If you use other endpoints than the one used in this page, however, be sure to check whether you need the test id or the kit id.

Retrieving the test results

The results can then be retrieved by calling the GET api.hurdle.bio/tests/v2/{testid} endpoint. The results look like this:

{
    "id": "6377bcd6cd7907948cb56ff7",
    "kitId": "MMM1234535",
    "productCode": "C1BLP05400",
    "status": "PROCESSED",
    "metadata": {
        "dateOfBirth": "1990-05-12",
        "gender": "f"
    },
    "registeredAt": "2022-11-18T17:11:50.243Z",
    "specimens": [
        {
            "id": "6377bcd6cd7907948cb56ff8",
            "barcode": "BLC2211006182093",
            "status": "PROCESSED",
            "testId": "6377bcd6cd7907948cb56ff7",
            "processedAt": "2022-11-18T17:14:31.493Z",
            "registeredAt": "2022-11-18T17:11:00.000Z",
            "accessionedAt": "2022-11-18T17:12:25.043Z",
            "specimenType": "CAPILLARY_BLOOD_DBS"
        }
    ],
    "biomarkerResults": [
        {
            "id": "6377bd775428f230ea2a7431",
            "result": "20",
            "specimenId": "6377bcd6cd7907948cb56ff8",
            "testId": "6377bcd6cd7907948cb56ff7",
            "interpretation": "NORMAL",
            "biomarker": {
                "id": "62c2c004cb575368fb1593ed",
                "name": "LDL Cholesterol",
                "code": "LDL",
                "unit": "mg/dl",
                "interpretationRule": {
                    "rule": "RANGE",
                    "value": {
                        "NORMAL": [
                            "<=99"
                        ],
                        "HIGH": [
                            ">99"
                        ]
                    }
                },
                "specimenType": "CAPILLARY_BLOOD_DBS"
            }
        },
        {
            "id": "6377bd775428f230ea2a742f",
            "result": "20",
            "specimenId": "6377bcd6cd7907948cb56ff8",
            "testId": "6377bcd6cd7907948cb56ff7",
            "interpretation": "LOW",
            "biomarker": {
                "id": "62c2bfaccb575368fb1593ec",
                "name": "Triglycerides",
                "code": "TGL",
                "unit": "mg/dl",
                "interpretationRule": {
                    "rule": "RANGE",
                    "value": {
                        "LOW": [
                            "<26"
                        ],
                        "NORMAL": [
                            ">=26",
                            "<=149"
                        ],
                        "HIGH": [
                            ">149"
                        ]
                    }
                },
                "specimenType": "CAPILLARY_BLOOD_DBS"
            }
        },
        {
            "id": "6377bd775428f230ea2a742d",
            "result": "20",
            "specimenId": "6377bcd6cd7907948cb56ff8",
            "testId": "6377bcd6cd7907948cb56ff7",
            "interpretation": "DIABETES",
            "biomarker": {
                "id": "62cea5a521d4c31a5ab7f63a",
                "name": "Hemoglobin A1c",
                "code": "HbA1c",
                "unit": "%",
                "interpretationRule": {
                    "rule": "RANGE",
                    "value": {
                        "NORMAL": [
                            "<5.7"
                        ],
                        "PRE_DIABETIC": [
                            ">=5.7",
                            "<=6.4"
                        ],
                        "DIABETES": [
                            ">6.4"
                        ]
                    }
                },
                "specimenType": "CAPILLARY_BLOOD_DBS"
            },
          # redacted for brevity
        }
    ],
    "productDisclaimer": {
        "disclaimer": "NULL"
    },
    "reportUrlPaths": [
        "/tests/v2/6377bcd6cd7907948cb56ff7/reports/967f5438-d1f1-43d2-acf7-48c2981fb448"
    ]
}

For each biomarker in the test, you can read the measurement, interpretation, and reference interpretation rules.

Edge cases

Sometimes things go wrong, and there is no result. For example, if there was not enough blood in a capillary blood test. You may then see error messages as text instead of the actual result, in the result field. The interpretation will then be indefinite. For example:

# ...
"interpretation": "Indefinite",
"result": "Quantity Not Sufficient"
# ...

Results

The result field contains the result as measured by the lab. It is typically numerical, although it could be categorical for some biomarkers (e.g. DETECTED). Alternatively, when something goes wrong, an error code can be returned. The list of possible result error codes is as follows:

Interpretation codes

The interpretation field of a result can be:

• Indefinite: this would happen if the result is an error (see above), or if for some reason an interpretation could not be applied (this would be the case for some biomarkers based on the phase of the fertility cycle, when we don't know which phase the test taker was in)
• Any of the following interpretation codes. Which codes are sent depend on each biomarker, and can depend on the lab (this is why some interpretations seem very similar to others). Note that the meaning detailed in the following table is only indicative: the official interpretation comes from a lab and consists only of that one keyword.

Items marked with an (*)asterisk are considered rarely used (few biomarkers).

Note that the interpretation rule relevant to the patient is returned with each result.

Note about critical results

When a lab detects a critical result, an escalation process immediately starts - before the results are even published. Some labs will then return this result as critical, while others will just report them as high or low. This means that:

• results that were critical and were escalated might not be flagged as critical in the results
• results that are flagged as critical do not require specific treatment as the process has already happened or started in parallel.

Units

The unit returned with the result will be one of the following:

mmol/L
g/L
IU/L
U/L
mg/L
pmol/L
nmol/L
mU/L
ug/L
%
mg/dL
IU/mL
x10^12/L
L/L
fL
x10^9/L
mmol/mol
mL/min/1.73m^2
pg/cell
[blank]
ratio
pg
ng/mL
pg/mL
ng/dL
µU/mL
kU/L
µmol/L
mIU/mL
µg/L
age acceleration (years)
mIU/L
kg/m2
MET minutes
h
score
servings/day
servings/week
µIU/mL