Appointments

An appointment is a scheduled blood draw session for a patient profile. Depending on the test_method, the draw takes place either at a physical test location or through a home kit mailed to the patient.

Fields

string

required

UUID auto-generated by Aniva. Use this to add panels, confirm the draw, and retrieve results.

profile_id

string

required

The UUID of the profile this appointment belongs to.

location_id

string

The UUID of the test location where the draw will take place. Null for home kit appointments.

scheduled_at

string

Scheduled blood draw datetime in ISO 8601 format. Returned with the test location’s offset (e.g. 2026-04-15T10:30:00+02:00) — the wall-clock in the string is the wall-clock at the location, so no separate timezone lookup is needed to render it. On create / update the value must include a timezone designator (either Z or an explicit offset like +02:00) and must be in the future.

status

string

required

Current lifecycle status. One of pending, confirmed, blood_drawn, or cancelled. See Lifecycle below. Lab-result completion granularity (partial vs done) is derived from Get Results; finer-grained shipment progression (in transit, delivered, etc.) is derived by following each entry in the inline shipments array to Get Shipment.

test_method

string

How the blood draw is performed: - practitioner — drawn at a test location by a healthcare professional - home — home blood draw kit mailed to the patient

created_at

string

required

ISO 8601 timestamp of when the appointment was created.

updated_at

string

ISO 8601 timestamp of the most recent update. Null if the appointment has never been updated.

profile

object

The full profile object for the patient, embedded in every appointment response.

Show properties

string

UUID of the associated profile.

first_name

string

Patient’s first name.

last_name

string

Patient’s last name.

string

Patient’s email address.

date_of_birth

string

Date of birth in YYYY-MM-DD format.

sex

integer

Biological sex per ISO/IEC 5218.

Lifecycle

Appointments expose four lifecycle states:

pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled

Status	Meaning
`pending`	The appointment is scheduled and awaiting confirmation. Can be updated or cancelled.
`confirmed`	Scheduling has been confirmed (e.g., by the practice), but blood has not yet been drawn. Can still be updated or cancelled.
`blood_drawn`	The kit barcode has been submitted via Confirm Blood Draw and the lab order pipeline has been triggered. Panels are frozen and the appointment cannot be rescheduled or cancelled.
`cancelled`	The appointment has been cancelled. Terminal — no further transitions.

The appointment status surface is intentionally coarse — finer-grained progression is exposed via dedicated endpoints:

Lab result completion (partial vs done) → Get Results — top-level status field is in_progress or completed.
Shipment progression (in transit, delivered, etc.) → follow each entry in the inline shipments array on the appointment to Get Shipment — each shipment carries its own status and a status_updates event log.

Confirming an appointment (moving it to blood_drawn) is irreversible. Once you submit the kit barcode, the lab order pipeline is triggered and cannot be undone. Updates and cancellations are only allowed while the appointment is in pending or confirmed status.

Listing appointments

Retrieve all appointments accessible to your API key:

GET /api/v1/appointments

Optionally pass ?profile_id={uuid} to filter by a specific profile. Without this parameter, a default time window (past 2 months to future 1 month) is applied.

Updating an appointment

Before the blood draw is confirmed, you can reschedule or change the test location:

PATCH /api/v1/appointments/{id}

Pass any combination of scheduled_at and location_id to update. Only include the fields you want to change.

Updates are only allowed before the blood draw — i.e. while the appointment is in pending or confirmed status. Once the appointment moves to blood_drawn or has been cancelled, it cannot be modified.

Cancelling an appointment

Cancel an appointment that is no longer needed:

DELETE /api/v1/appointments/{id}

This sets the appointment status to cancelled. The cancelled appointment is returned in the response.

Cancellation is only allowed before the blood draw — i.e. while the appointment is in pending or confirmed status. Appointments that have already moved to blood_drawn cannot be cancelled.

Adding panels

Before confirming the blood draw, add the blood test panels you want to run by calling:

POST /api/v1/appointments/{id}/panels

Pass an array of panel UUIDs in the panel_ids field. Panel IDs are provided by Aniva for your partner account.

Panels must be added before the blood draw — i.e. while the appointment is in pending or confirmed status. You cannot add or change panels once the appointment has moved to blood_drawn.

Removing panels

If you need to remove panels before the blood draw, call:

DELETE /api/v1/appointments/{id}/panels

Pass an array of panel UUIDs in the panel_ids field. All specified panels must currently be associated with the appointment.

Like adding panels, removal is only allowed before the blood draw — i.e. while the appointment is in pending or confirmed status. Panels cannot be removed once the appointment has moved to blood_drawn.

Individual biomarkers

If your API key is granted access to a custom container panel, you can attach individual biomarkers to an appointment without picking a panel. This is useful when a practitioner wants an à la carte selection of tests rather than a pre-defined bundle. Aniva exposes two predefined custom container panels — pick the one matching the lab the biomarkers should route to:

Panel name	UUID	Routes to
Aniva Custom ZotzKlimas	`00000000-0000-0000-0000-000000000aff`	ZotzKlimas
Aniva Custom Labclinic	`00000000-0000-0000-0000-000000000bff`	Labclinic

Add biomarkers (idempotent — already-attached biomarkers are kept):

PATCH /api/v1/appointments/{id}/custom-snapshot

Remove biomarkers (every ID must currently be attached, otherwise 404):

DELETE /api/v1/appointments/{id}/custom-snapshot

Both endpoints take a required panel_id (UUID of one of the custom panels above) and a biomarker_ids array. Use List Biomarkers to discover biomarker IDs. When removing, pass the same panel_id you originally wrote the biomarkers under.

When the chosen panel routes exclusively to a single lab — i.e. Aniva Custom ZotzKlimas (ZK) or Aniva Custom Labclinic (LC) — the server validates that the post-change biomarker set is orderable at that lab as a coherent combination. Partial sets that would force the lab to also bill biomarkers you did not request — or removals that leave an incoherent residual set — are rejected with 400 and a multi-candidate explanation listing the missing biomarkers per orderable option.

Like panel modifications, individual biomarkers can only be added or removed before the blood draw — i.e. while the appointment is in pending or confirmed status. Once the appointment moves to blood_drawn the custom snapshot is frozen.

Previewing tube requirements

After adding panels or custom biomarkers, preview the physical blood collection tubes that will be needed for the blood draw:

GET /api/v1/appointments/{id}/preview

The response includes the tube type, name, cap color, volume, and count for each required tube. This helps practitioners prepare the correct materials before the blood draw. The response also includes routing and pricing fields reserved for future use (currently null).

The preview reflects the currently attached panels and biomarkers. If you add or remove panels after previewing, call the preview endpoint again to get updated tube requirements.

Confirming the blood draw

After the blood is drawn, submit the kit barcode to trigger the lab order pipeline:

POST /api/v1/appointments/{id}/confirm

This moves the appointment status to blood_drawn and initiates lab processing. This action is irreversible.

Shipment pickup

POST /api/v1/appointments/pickup and the shipment_picked_up appointment status are deprecated. The endpoint is retained as a no-op that returns 200 with Deprecation and Warning response headers so existing integrations don’t break — see Confirm Shipment Pickup (deprecated).

To track post-blood-draw progression, follow each entry in the appointment’s inline shipments array to Get Shipment — each shipment carries its own status and a status_updates history.

Linking shipments

An appointment can be linked to one or more shipments (and vice versa — the relation is many-to-many). The current link set surfaces inline on both sides:

on the appointment, as a shipments array of { id, added_at } entries;
on the shipment, as an appointments array of { id, added_at } entries.

Both arrays are oldest-link first. Each id cross-references the canonical detail endpoint (Get Shipment / Get Appointment) for the full payload. Shipments are linked at creation time via the appointment_id field on Create Shipment. After creation, manage links on the appointment side with Attach Shipments to Appointment and Detach Shipments from Appointment, or symmetrically from the shipment side with Attach Appointments to Shipment and Detach Appointments from Shipment. Each mutation returns the parent resource (Appointment / Shipment) with the post-mutation link array populated. The mutation rule is: links can be created or removed when EITHER

the appointment is past blood-draw (blood_drawn), or
the shipment was created less than 24 hours ago.

Outside that window the link is locked so historical records stay stable.

Retrieving lab results

Once the lab has processed the blood samples, retrieve clinical and genetic results:

GET /api/v1/appointments/{id}/results

The response includes planned tests (status planned) alongside received results, so you can track what is still pending. The top-level status field is in_progress until every submission arrives, then completed — use this to derive whether the appointment’s lab work is done. Lab report PDFs are referenced in the documents array — use GET /api/v1/documents/{id} to download them.

Example appointment

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T10:30:00+02:00",
  "status": "confirmed",
  "test_method": "practitioner",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "date_of_birth": "1990-06-15",
    "sex": 2
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2604154821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ]
}

​Fields

​Lifecycle

​Listing appointments

​Updating an appointment

​Cancelling an appointment

​Adding panels

​Removing panels

​Individual biomarkers

​Previewing tube requirements

​Confirming the blood draw

​Shipment pickup

​Linking shipments

​Retrieving lab results

​Example appointment

Fields

Lifecycle

Listing appointments

Updating an appointment

Cancelling an appointment

Adding panels

Removing panels

Individual biomarkers

Previewing tube requirements

Confirming the blood draw

Shipment pickup

Linking shipments

Retrieving lab results

Example appointment