Get Lab Results

GET

api

home-kit-orders

{id}

results

curl --request GET \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results \
  --header 'x-api-key: YOUR_API_KEY'

{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "e9f1a3c5-6b7d-4c2e-8a4f-1d3b5c7e9f02",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "reference_range_aniva": {
        "normal_min": 30,
        "normal_max": 80,
        "optimal_min": 40,
        "optimal_max": 60
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "reference_range_aniva": null,
      "tested_at": null,
      "comment": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "1b3d5f7a-9c2e-4a6b-8d0f-2e4a6c8b0d13",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}

{
  "error": "Home kit order not found"
}

Retrieve clinical and genetic lab results for a home kit order, along with document references for lab report PDFs. Every biomarker ordered for the kit appears in the response, so you can track the whole order rather than only what has come back. Results file under the order’s lab_code — the laboratory order is placed at activation, and the lab reports markers individually as they are analysed, so a partial payload is normal and the top-level status stays in_progress until the final report. Read status on each result before using its value:

Tests still outstanding appear with status planned while the order is in_progress. You can call this endpoint before activation — every ordered marker is then planned.
Results the lab delivered but that must not be used clinically appear with status fault or undeliverable, and carry a status_reason explaining why. A fault result still has its value populated — that value is wrong. Never present it as a finding.

Use Download Document to download lab report PDFs referenced in the documents array. You do not need to poll this endpoint. Subscribe to home_kit_order.results.updated or home_kit_order.results.completed webhooks, and call it when an event arrives. Polling still works as a fallback. Requires the results_view scope — lab results and documents are always gated by it, the same as appointment results and Download Document — plus the home_kit_orders_view or home_kit_orders_manage scope to access the kit order itself.

Request

Path parameters

string

required

Unique identifier (UUID) of the home kit order to retrieve results for.

Response

On success, the API returns 200 OK with the results object.

string

required

Overall results status. One of:

in_progress — some requisitions are still at the laboratory.
completed — every requisition has closed and at least one reported.
fault — every requisition died without reporting. Nothing is owed.

object[]

required

One entry per laboratory requisition — a draw spanning several tubes or laboratories has several. The top-level status is completed once every entry has closed and one reported.

Show submission object

string

Lab code (tube barcode) this requisition was filed under. May be null when the lab filed none.

string

required

in_progress while the laboratory is still working on it, completed once its report is final, or fault when the requisition was rejected or abandoned and will never report — the sample is often moved to another laboratory, which then files its own entry.

object[]

required

Array of clinical biomarker results.

Show clinical result object

string

Lab result row identifier (UUID). It stays the same when the lab corrects that row, so use it to upsert. null for a planned result.

string

required

Result status. One of:

planned — ordered, not returned by the lab yet. value is null.
received — delivered by the lab.
corrected — delivered, then revised by a human. value is the corrected value.
fault — delivered but confirmed wrong; do not use clinically. value is populated with the wrong figure. See status_reason.
undeliverable — the lab could not produce a value. value is null. See status_reason.

string

required

Why the result is unusable. Populated for fault and undeliverable, null for every other status.Distinct from comment, which is the lab’s own note on the report — comment is empty on most faulted results, so treat status_reason as the authoritative explanation.

string

Lab code (tube barcode) the result was filed under — one of the order’s lab codes. null for a planned result and for results the lab reported without a code.

integer

required

Biomarker identifier.

string

required

Biomarker display name.

string

Biomarker category (e.g., Hormones, Vitamins). May be null.

number

Effective result value (corrected if available, otherwise raw). May be null.

string

Comparison operator for the value: eq (equals), lt (less than), or gt (greater than). May be null.

integer

Measurement unit identifier. May be null.

string

Measurement unit display name. May be null.

object

Reference ranges reported by the lab for this result, converted to the same unit as value. null when the lab reported no range.A bound the lab left open stays null, so a one-sided interval populates only its own end — an upper threshold arrives as normal_min: null, normal_max: 50, a lower one as normal_min: 55, normal_max: null. Do not read a null bound as zero or unbounded-by-default; read it as “the lab set no limit on that side”.Each result carries the range it was measured against, so a patient whose results span several draws or several labs gets the correct interval per result rather than the most recent one.

Show reference range

number

Lower bound of normal range. May be null.

number

Upper bound of normal range. May be null.

number

Lower bound of optimal range. May be null.

number

Upper bound of optimal range. May be null.

string

Why reference_range_lab is null. null when reference_range_lab is present, and on a planned result.

not_provided: no range exists. The lab sent none, or Aniva calculated the value. Show “Not applicable”.
lab_text_only: the lab printed only text, such as a target, a risk tier or a life-stage range. Show lab_reported.reference_range.
not_measured: the result is undeliverable, so there is no value to compare. Show status_reason.

object

Aniva-curated reference ranges adjusted for age, sex, and pregnancy status, on the same scale as value. null when your key lacks the aniva_reference_ranges_view scope, or when Aniva has no range of its own for this biomarker.

Show reference range

number

Lower bound of normal range. May be null.

number

Upper bound of normal range. May be null.

number

Lower bound of optimal range. May be null.

number

Upper bound of optimal range. May be null.

string

Date the test was performed in YYYY-MM-DD format. May be null.

string

Optional comment on the result. May be null.

object

The performing lab’s own report line, verbatim — for reading this payload against the lab’s PDF. May be null when we hold no raw record for the result.Every other field on a result is normalized: value and unit are converted to the biomarker’s default unit, and biomarker_name is our name for the analyte, not the lab’s. The fields below are not. Treat them as the as-printed reference and the canonical fields as the consistency cross-check.Numbers here are the lab’s own bounds on the lab’s own scale — reference_range_min and reference_range_max are not unit-converted and will differ from reference_range_lab wherever the two scales differ. A bound the lab left open stays null; nothing is inferred or defaulted.

Show lab reported

string

Analyte name as printed by the lab. May be null.

string

The lab’s own analyte code. May be null.

string

Report section heading, e.g. Klinische Chemie. May be null.

string

Value as printed. A string, so non-numeric results survive intact (<0.04, negativ, 1:100). May be null.

string

Unit as printed, e.g. U/l. May be null.

string

Reference interval as printed, including one-sided thresholds: 40 - 129, < 50, > 55. May be null.

number

The lab’s lower bound, unconverted. null for an interval the lab left open below.

number

The lab’s upper bound, unconverted. null for an interval the lab left open above.

string

The lab’s abnormality flag for this line: normal, high, low, critical_high, critical_low, abnormal. A code we do not recognize passes through as the lab sent it. May be null.

string

The lab’s result status: final, preliminary, correction, incomplete, partial, deleted, cannot_be_obtained. A preliminary value can still be revised. A later results.updated webhook tells you when to fetch again. May be null.

string

The lab’s own note on this line. Column padding is collapsed; wording is untouched. May be null.

object[]

required

Array of genetic biomarker results.

Show genetic result object

string

Lab result row identifier (UUID). It stays the same when the lab corrects that row, so use it to upsert. null for a planned result.

string

required

Result status. One of:

planned — ordered, not returned by the lab yet.
received — delivered by the lab.
fault — delivered but confirmed wrong; do not use clinically. See status_reason.
undeliverable — the lab could not produce a genotype. See status_reason.

string

required

Why the result is unusable. Populated for fault and undeliverable, null for every other status.

string

Lab code (tube barcode) the result was filed under. null for a planned result and for results the lab reported without a code.

integer

required

Biomarker (gene) identifier.

string

required

Gene symbol (e.g., APOE, MTHFR).

string

Genotype display (e.g., E3/E4). May be null.

string

Overall clinical significance. One of pathogenic, likely_pathogenic, uncertain, likely_benign, benign, high_risk, moderate_risk, low_risk, protective, drug_response, poor_metabolizer, or rapid_metabolizer. May be null.

string

Risk description for this genotype. May be null.

string

Date the test was performed in YYYY-MM-DD format. May be null.

string

Optional comment on the result. May be null.

object[]

required

Detected genetic variants.

Show variant object

string

required

Variant common name (e.g., APOE E4).

string

Variant-level clinical significance. May be null.

string

Variant description. May be null.

string

HGVS coding DNA notation. May be null.

string

HGVS protein notation. May be null.

object[]

required

Associated conditions.

Show condition object

string

required

Condition/disease name.

string

Description of the variant-condition association. May be null.

string

Short badge text for display. May be null.

object[]

required

Single nucleotide variants defining this variant.

Show SNV object

string

required

dbSNP identifier (e.g., rs429358).

string

required

Variant allele (A, C, G, T, del, ins, or undetermined).

string

required

Population reference allele.

string

HGVS coding DNA notation. May be null.

string

HGVS protein notation. May be null.

object[]

required

Lab report documents. Use GET /api/v1/documents/{id} to download each file.

Show document object

string

required

File identifier (UUID). Pass to Download Document to retrieve the file.

string

required

File name. Download Document sends the same name in Content-Disposition. It holds a date, the document title and the lab code, e.g. 20260405 - Quade Befund - 7642001234.pdf. Use it for display only. Read the lab code from lab_code, not from the name.

string

required

File name exactly as the source delivered it, e.g. 7642100312_B0012_FA_V.pdf from the lab or the member’s own name for an upload. Aniva does not change it.

string

required

Who delivered the file. One of lab (the laboratory sent it), member_upload (the member uploaded it) or staff_upload (Aniva staff uploaded it).

string

required

Media type of the file, e.g. application/pdf, image/jpeg or text/csv. Most lab reports are PDFs.

string

Version of the file content. It changes whenever the bytes change, so compare it to the value you stored to see whether to download again. Download Document sends it quoted as the standard HTTP ETag header. May be null when the stored file is missing.

integer

File size in bytes. May be null when the stored file is missing.

string

Lab code (tube barcode) the report belongs to. May be null when the lab filed none.

Error responses

Status	Description
`400`	Invalid ID format — the provided value is not a valid UUID.
`403`	Forbidden — your API key is missing the `results_view` scope, is missing both `home_kit_orders_view` and `home_kit_orders_manage`, or the home kit order is outside your access context.
`404`	Home kit order not found.
`500`	Internal server error.

curl --request GET \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results \
  --header 'x-api-key: YOUR_API_KEY'

{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "e9f1a3c5-6b7d-4c2e-8a4f-1d3b5c7e9f02",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "reference_range_aniva": {
        "normal_min": 30,
        "normal_max": 80,
        "optimal_min": 40,
        "optimal_max": 60
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "reference_range_aniva": null,
      "tested_at": null,
      "comment": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "1b3d5f7a-9c2e-4a6b-8d0f-2e4a6c8b0d13",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}

{
  "error": "Home kit order not found"
}

curl --request GET \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results \
  --header 'x-api-key: YOUR_API_KEY'

{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "e9f1a3c5-6b7d-4c2e-8a4f-1d3b5c7e9f02",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "reference_range_aniva": {
        "normal_min": 30,
        "normal_max": 80,
        "optimal_min": 40,
        "optimal_max": 60
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "reference_range_aniva": null,
      "tested_at": null,
      "comment": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "1b3d5f7a-9c2e-4a6b-8d0f-2e4a6c8b0d13",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}

{
  "error": "Home kit order not found"
}

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Pricing

Units

Locations

Documents

Shipments

Webhooks

Request

Path parameters

Response

Error responses

​Request

​Path parameters

​Response

​Error responses

Request

Path parameters

Response

Error responses