Results

Fetching test results as FHIR documents: the download flow, how to read the Bundle structure, out-of-range and critical values, and failure scenarios.

Fetching results

When an order item reaches results.results_ready (via webhook), fetch the result:

GET /api/v1/results/{order_item_id}?test_taker_id={test_taker_id}

Both identifiers are required. test_taker_id arrives on every result webhook (and is recoverable from GET /api/v1/orders/{orderID} under items[].test_taker_ids).

{
  "download_url": "https://storage.googleapis.com/.../normalised.json?X-Goog-Signature=...",
  "format": "json",
  "expires_at": "2025-11-19T19:08:04.400Z"
}

The presigned download_url is valid for 15 minutes. Re-call the endpoint to mint a fresh URL rather than caching it. Each order item holds at most one panel, so a result is uniquely identified by its order_item_id.

To find results across your account (e.g. ready but unacknowledged), use the GET /api/v1/results index - see Managing orders.

Reading the FHIR document

The download is a FHIR Bundle (JSON) containing three resource types:

• DiagnosticReport - the panel: which observations it contains (result references), when it was collected (effectiveDateTime) and issued, and the subject patient.

• Patient - the test taker's demographics as registered at activation.

• Observation - one per biomarker: the code (test identifier and display name), valueQuantity (numeric value + unit), referenceRange (normal bounds), and interpretation (HL7 coding).

You mostly iterate the Bundle's entry array, pick out the Observation resources, and read value, unit, range, and interpretation from each.

Out-of-range results

Compare valueQuantity.value against referenceRange. In the example below, HDL Cholesterol is below normal, which you can observe from:

• low: 40.0, high: 100.0

• value: 35.2

• interpretation code L ("Below low normal")

Interpretation codes follow HL7 table 0078: N normal, L below low normal, H above high normal, with LL / HH marking critical values.

Critical results - must be handled properly

Depending on the test supplier you may receive a results.escalation_raised webhook indicating the overall severity of the result set, with an escalation_level of not_escalated, very_low, low, medium, high, or very_high, and an acknowledgment_due_by deadline. In critical cases the interpretation field will typically carry HH or LL codes.

Escalated results demand prompt review and acknowledgment - see Acknowledging Results and Webhooks.

Failed tests

• results.sample_rejected webhooks carry a failure_cause (e.g. contamination) when the lab rejects a sample.

• results.lab_processing_error indicates the lab could not process the sample.

In either case there will be no result document to fetch for that item; handle these paths in your product flow (e.g. offer a replacement kit).

Example result document

{
  "resourceType": "Bundle",
  "type": "collection",
  "timestamp": "2026-07-20T15:29:24+00:00",
  "entry": [
    {
      "fullUrl": "DiagnosticReport/dr-252463239248650243",
      "resource": {
        "resourceType": "DiagnosticReport",
        "id": "dr-252463239248650243",
        "code": { "text": "Laboratory Panel" },
        "status": "final",
        "effectiveDateTime": "2026-07-20T15:29:23+00:00",
        "issued": "2026-07-20T15:29:24+00:00",
        "subject": { "reference": "Patient/252463822202380289" },
        "result": [
          { "display": "Total Cholesterol", "reference": "Observation/obs-252463239248650243-CHOL" },
          { "display": "HDL Cholesterol", "reference": "Observation/obs-252463239248650243-HDL" },
          { "display": "Hemoglobin A1c", "reference": "Observation/obs-252463239248650243-HBA1C" }
        ]
      }
    },
    {
      "fullUrl": "Patient/252463822202380289",
      "resource": {
        "resourceType": "Patient",
        "id": "252463822202380289",
        "name": [{ "family": "Doe", "given": ["John"] }],
        "gender": "male",
        "birthDate": "1970-01-01",
        "address": [
          {
            "line": ["123 Test Street", "Apt 4B"],
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "94102",
            "country": "US"
          }
        ],
        "telecom": [
          { "system": "email", "value": "[email protected]" },
          { "system": "phone", "value": "[phone]" }
        ]
      }
    },
    {
      "fullUrl": "Observation/obs-252463239248650243-HDL",
      "resource": {
        "resourceType": "Observation",
        "id": "obs-252463239248650243-HDL",
        "status": "final",
        "code": {
          "coding": [{ "code": "HDL", "display": "HDL Cholesterol" }],
          "text": "HDL Cholesterol"
        },
        "subject": { "reference": "Patient/252463822202380289" },
        "effectiveDateTime": "2026-07-20T15:29:23+00:00",
        "issued": "2026-07-20T15:29:24+00:00",
        "valueQuantity": { "value": 35.2, "unit": "mg/dL", "code": "mg/dL" },
        "referenceRange": [
          { "low": { "value": 40 }, "high": { "value": 100 }, "text": "40.0 - 100.0" }
        ],
        "interpretation": [
          {
            "coding": [
              {
                "code": "L",
                "display": "Below low normal",
                "system": "http://terminology.hl7.org/CodeSystem/v2-0078"
              }
            ]
          }
        ]
      }
    },
    {
      "fullUrl": "Observation/obs-252463239248650243-HBA1C",
      "resource": {
        "resourceType": "Observation",
        "id": "obs-252463239248650243-HBA1C",
        "status": "final",
        "code": {
          "coding": [{ "code": "HBA1C", "display": "Hemoglobin A1c" }],
          "text": "Hemoglobin A1c"
        },
        "subject": { "reference": "Patient/252463822202380289" },
        "effectiveDateTime": "2026-07-20T15:29:23+00:00",
        "issued": "2026-07-20T15:29:24+00:00",
        "valueQuantity": { "value": 5.2, "unit": "%", "code": "%" },
        "referenceRange": [
          { "low": { "value": 4 }, "high": { "value": 5.6 }, "text": "4.0 - 5.6" }
        ],
        "interpretation": [
          {
            "coding": [
              {
                "code": "N",
                "display": "Normal",
                "system": "http://terminology.hl7.org/CodeSystem/v2-0078"
              }
            ]
          }
        ]
      }
    }
  ]
}