Add Individual Biomarkers

PATCH

api

appointments

{id}

biomarkers

curl --request PATCH \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/biomarkers \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "biomarker_ids": [45, 43, 42]
  }'

{
  "success": true
}

{
  "error": "ZK biomarker validation failed: the requested biomarker set does not match any orderable ZK panel combination.\nTo proceed, choose one of the options below and add the missing biomarkers:\n  Option 1 — order panels [662, 663, 665], also add biomarkers: LDL Cholesterol (#43), HDL Cholesterol (#42)",
  "validation": {
    "failures": [
      {
        "lab": "zotzklimas",
        "candidates": [
          {
            "order_ids": [662, 663, 665],
            "missing_biomarkers": [
              { "id": 43, "name": "LDL Cholesterol" },
              { "id": 42, "name": "HDL Cholesterol" }
            ]
          }
        ]
      }
    ]
  }
}

{
  "error": "Individual biomarkers cannot be modified after blood draw has been confirmed"
}

{
  "error": "Biomarkers not found: 99999"
}

Add one or more individual biomarkers to an appointment as à-la-carte tests, outside any pre-built panel. Routing decisions are made downstream by the order-logistics pipeline based on each biomarker’s per-lab mappings. The resulting set is validated synchronously against each lab’s closure rules. Some biomarkers can only be obtained by ordering them together with others — an LDL/HDL ratio, for example, is delivered by an order that also returns LDL and HDL, so requesting the ratio on its own isn’t a coherent order. (Those same components are what the ratio is priced as — see the pricing breakdown on List Biomarkers.) When the set can’t be cleanly ordered, the call returns 400 with a validation payload and nothing is persisted, so you can trial-and-error your way to a valid set:

PATCH … { "biomarker_ids": [45] } (LDL/HDL ratio alone) → 400; validation.failures[].candidates[].missing_biomarkers lists LDL and HDL.
PATCH … { "biomarker_ids": [45, 43, 42] } (ratio + LDL + HDL) → 200.

This call is idempotent: biomarkers already on the appointment are kept.

Biomarkers cannot be added after you call Confirm Blood Draw. Attempting to modify a confirmed appointment returns 409 Conflict.

Request

Path parameters

string

required

Unique identifier (UUID) of the appointment.

Body parameters

number[]

required

Array of biomarker IDs to attach. Must contain at least one item. Use List Biomarkers to discover IDs.

Response

On success, the API returns 200 OK confirming the biomarkers have been attached.

boolean

true when the biomarkers have been successfully added to the appointment.

Closure-validation failure (`400`)

When the resulting set can’t be cleanly ordered, the body is a BiomarkerValidationError (see the 400 schema in the API playground above):

error — a human-readable summary of why the set can’t be ordered.
validation.failures[] — present only on closure-validation failures (absent on plain body-validation errors). One entry per lab that rejected the set, each with candidates[]. A candidate lists the order_ids it would place and the missing_biomarkers ({ id, name }) you’d need to add — keep your originals, add those, and retry.

Error responses

Status	Description
`400`	`biomarker_ids` empty / non-integer, or the resulting set fails closure validation (`validation.failures`).
`403`	Forbidden — missing scope or appointment outside access context.
`404`	Appointment or one or more biomarkers not found.
`409`	Conflict — biomarkers cannot be modified after the blood draw has been confirmed.
`500`	Internal server error.

curl --request PATCH \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/biomarkers \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "biomarker_ids": [45, 43, 42]
  }'

{
  "success": true
}

{
  "error": "ZK biomarker validation failed: the requested biomarker set does not match any orderable ZK panel combination.\nTo proceed, choose one of the options below and add the missing biomarkers:\n  Option 1 — order panels [662, 663, 665], also add biomarkers: LDL Cholesterol (#43), HDL Cholesterol (#42)",
  "validation": {
    "failures": [
      {
        "lab": "zotzklimas",
        "candidates": [
          {
            "order_ids": [662, 663, 665],
            "missing_biomarkers": [
              { "id": 43, "name": "LDL Cholesterol" },
              { "id": 42, "name": "HDL Cholesterol" }
            ]
          }
        ]
      }
    ]
  }
}

{
  "error": "Individual biomarkers cannot be modified after blood draw has been confirmed"
}

{
  "error": "Biomarkers not found: 99999"
}

Remove Panels

Remove Individual Biomarkers

curl --request PATCH \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/biomarkers \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "biomarker_ids": [45, 43, 42]
  }'

{
  "success": true
}

{
  "error": "ZK biomarker validation failed: the requested biomarker set does not match any orderable ZK panel combination.\nTo proceed, choose one of the options below and add the missing biomarkers:\n  Option 1 — order panels [662, 663, 665], also add biomarkers: LDL Cholesterol (#43), HDL Cholesterol (#42)",
  "validation": {
    "failures": [
      {
        "lab": "zotzklimas",
        "candidates": [
          {
            "order_ids": [662, 663, 665],
            "missing_biomarkers": [
              { "id": 43, "name": "LDL Cholesterol" },
              { "id": 42, "name": "HDL Cholesterol" }
            ]
          }
        ]
      }
    ]
  }
}

{
  "error": "Individual biomarkers cannot be modified after blood draw has been confirmed"
}

{
  "error": "Biomarkers not found: 99999"
}

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Units

Locations

Documents

Shipments

Add Individual Biomarkers

Request

Path parameters

Body parameters

Response

Closure-validation failure (`400`)

Error responses

​Request

​Path parameters

​Body parameters

​Response

​Closure-validation failure (400)

​Error responses

Request

Path parameters

Body parameters

Response

Closure-validation failure (`400`)

Error responses