> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/vantage-api-docs/documentation/results.md).

# Results

## 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`).

```json
{
  "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](/vantage-api-docs/documentation/managing-orders.md#list-results).

## Reading the FHIR document

The download is a [FHIR](https://hl7.org/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](https://hl7-definition.caristix.com/v2/HL7v2.8/Tables/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](/vantage-api-docs/important-information/acknowledging-results.md) and [Webhooks](/vantage-api-docs/documentation/webhooks.md#order_itemresults_status_change).

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

```json
{
  "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": "john.doe@example.com" },
          { "system": "phone", "value": "+14155551234" }
        ]
      }
    },
    {
      "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"
              }
            ]
          }
        ]
      }
    }
  ]
}
```