Skip to main content
After a blood draw is confirmed and the lab processes the samples, results become available on the appointment. Results are retrieved via GET /api/v1/appointments/{id}/results and include clinical biomarker results, genetic biomarker results, and downloadable lab report documents.
Requires the RESULTS_VIEW scope.

​
Results status

The top-level status field on the results response indicates overall processing progress:
StatusMeaning
in_progressSome submissions are still being processed by the lab.
completedAll submissions have been processed and results are final.
Individual results within the response have their own per-result status (see below), so you can display partial results while the overall status is still in_progress.

​
Clinical results

Clinical results represent standard blood biomarker measurements — things like Vitamin D levels, cholesterol, thyroid hormones, and so on. Each clinical result includes:
  • biomarker_name and category — what was measured and its grouping (e.g., Vitamins, Hormones).
  • value and value_operator — the effective measurement. The operator is eq (equals) for exact values, or lt/gt when the lab reports a value below or above the measurable range.
  • unit — the measurement unit (e.g., ng/mL, µIU/mL).
  • reference_range_lab — normal and optimal min/max bounds as reported by the lab.
  • reference_range_aniva — Aniva-curated reference ranges adjusted for age, sex, and pregnancy status.
  • tested_at — the date the test was performed.

​
Clinical result statuses

StatusMeaning
plannedThe test is ordered but results have not arrived from the lab yet.
receivedThe lab has returned a result.
correctedA human reviewer has revised the lab-reported value.
When displaying results to patients, use the value field directly — it already reflects the corrected value when one exists.

​
Genetic results

Genetic results represent gene-level findings from DNA analysis. Each result corresponds to a gene (e.g., APOE, MTHFR) and includes:
  • gene — the gene symbol.
  • genotype — the detected genotype (e.g., E3/E4).
  • clinical_significance — an ACMG-based classification of the finding.
  • risk_description — a human-readable explanation of what the genotype means.
  • variants — the specific genetic variants detected, each with SNV-level detail.

​
Clinical significance values

ValueCategory
pathogenic, likely_pathogenicDisease-causing or likely disease-causing
uncertainVariant of uncertain significance (VUS)
likely_benign, benignNot disease-causing
high_risk, moderate_risk, low_riskRisk level classification
protectiveProtective variant
drug_response, poor_metabolizer, rapid_metabolizerPharmacogenomic findings

​
Genetic result statuses

StatusMeaning
plannedThe test is ordered but results have not arrived yet.
receivedThe lab has returned a result.

​
Variant structure

Each genetic result contains a variants array. Each variant includes:
  • name — common name (e.g., APOE E4).
  • clinical_significance — variant-level significance (may differ from the gene-level significance).
  • conditions — associated diseases/conditions with descriptions.
  • snvs — the underlying single nucleotide variants, each with rs_id, allele, reference_allele, and optional HGVS notation.

​
Documents

The documents array in the results response contains references to downloadable lab report PDFs. Each document has:
  • id — a file UUID. Pass this to GET /api/v1/documents/{id} to download the file.
  • file_name — the original file name (e.g., lab-report-2026-04-05.pdf).
Downloading documents also requires the RESULTS_VIEW scope. Access is validated against the profile that owns the document.

​
Example results response

{
  "status": "in_progress",
  "clinical_results": [
    {
      "status": "received",
      "biomarker_id": 42,
      "biomarker_name": "Vitamin D (25-OH)",
      "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_aniva": {
        "normal_min": 30,
        "normal_max": 80,
        "optimal_min": 40,
        "optimal_max": 60
      },
      "tested_at": "2026-04-05",
      "comment": null
    },
    {
      "status": "planned",
      "biomarker_id": 87,
      "biomarker_name": "TSH",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_aniva": null,
      "tested_at": null,
      "comment": null
    }
  ],
  "genetic_results": [
    {
      "status": "received",
      "biomarker_id": 201,
      "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": "lab-report-2026-04-05.pdf"
    }
  ]
}