Skip to main content
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

​
id
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
ISO 8601 datetime of the scheduled blood draw. Must be a future datetime when creating the appointment.
​
status
string
required
Current lifecycle status. One of scheduled, confirmed, completed, or cancelled. See Lifecycle below.
​
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.

​
Lifecycle

Appointments move through the following statuses: 
scheduled → confirmed → completed
                ↓
           cancelled
StatusMeaning
scheduledThe appointment has been created but the blood draw has not yet been confirmed.
confirmedThe barcode has been submitted and a lab order has been triggered.
completedLab results have been processed.
cancelledThe appointment has been cancelled.
Confirming an appointment (moving it from scheduled to confirmed) is irreversible. Once you submit the kit barcode, the lab order pipeline is triggered and cannot be undone.

​
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 while the appointment is in scheduled status. You cannot add or change panels after the appointment is confirmed.

​
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 from scheduled to confirmed and initiates lab processing. This action is irreversible.

​
Shipment pickup

After blood has been drawn for a batch of appointments, record that the courier has picked up the samples: 
POST /api/v1/appointments/pickup
Pass an array of appointment_ids for which tubes have been collected. This transitions blood_drawn appointments to in_transit. Appointments already in transit or completed are silently skipped.
Requires the TEST_SESSIONS_OPERATE or TEST_SESSIONS_MANAGE scope.

​
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. Lab report PDFs are referenced in the documents array — use GET /api/v1/documents/{id} to download them.
Requires the RESULTS_VIEW scope.

​
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-15T08:30:00Z",
  "status": "scheduled",
  "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
  }
}