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"
# ...