Skip to main content
POST
Schedule a blood draw appointment for a patient profile at a specific test location. Once created, the appointment enters confirmed status by default (some locations may instead default to pending — this is a per-location setting). Use Add Panels to attach blood test panels before confirming the blood draw.
A profile can hold at most one appointment per location and time. Creating an appointment for a slot the profile already occupies returns 409 with the existing appointment_id instead of a second appointment — so a retried or accidentally repeated request can never duplicate a booking. See Duplicate appointments.
Send an optional Idempotency-Key header to make this create safe to retry — a repeat of the same key returns the original response instead of creating a second one. See Idempotency. Requires the test_sessions_schedule scope.

​
Request

​
Body parameters

​
string
required
UUID of the patient profile to create the appointment for.
​
string
required
UUID of the test location where the blood draw will take place. Use List Locations to find available location IDs.
​
string
required
Date and time of the appointment in ISO 8601 format (e.g., 2026-05-15T10:30:00Z or 2026-05-15T12:30:00+02:00). Must include a timezone designator — either Z or an explicit offset like +02:00; naive datetimes are rejected. Must be in the future.Must be an exact slot start on the location’s grid, and the slot must still have capacity — read Get Availability first. Off-grid times return 400; a slot that has filled up returns 409. At Aniva-operated locations it must also be at least 12 hours out — see Minimum notice.
​
string[]
Up to 5 addresses that each get one email once every lab result is final. The email links to the result page in the Aniva admin panel. Your key needs results_view access to the patient, else 403. See Results-ready emails.

​
Response

On success, the API returns 201 Created with the new appointment.
​
string
required
Unique appointment identifier (UUID).
​
string
required
UUID of the profile this appointment belongs to.
​
string
UUID of the test location where the draw takes place.
​
string
Scheduled appointment datetime as a UTC instant (ISO 8601 with Z suffix, e.g. 2026-05-15T10:30:00Z). May be null.
​
string
required
Current appointment status. One of pending, confirmed, blood_drawn, or cancelled. Lab-result completion granularity is derived from Get Results; finer-grained shipment progression from each entry in the inline shipments array (see below) followed to Get Shipment.
​
string
Free-text reason captured when the appointment was cancelled (e.g. no-show, late cancellation, ‘Failed. Repeat required’). null unless status is cancelled.
​
string[]
required
Addresses that each get one email once every lab result is final, lowercased. Empty when off. See Results-ready emails.
​
object
required
The patient profile associated with this appointment.
​
AppointmentPanel[]
required
Panels currently attached to this appointment. Empty for newly-created appointments — attach via Add Panels. Look up panel details (name, biomarkers) via List Panels.
​
AppointmentIndividualBiomarker[]
required
À-la-carte biomarkers attached to this appointment outside any panel. Empty for newly-created appointments — attach via Add Individual Biomarkers. Cross-reference each biomarker_id against List Biomarkers for display data.
​
AppointmentShipmentLink[]
required
Shipments linked to this appointment, oldest-link first. Empty for newly-created appointments — link via Create Shipment (with appointment_id) or Attach Appointments to Shipment.
​
string[]
required
Lab codes (tube barcodes) recorded for this appointment, in scan order. Empty until the blood draw is confirmed. A venous draw carries one code printed on every tube; a pharmacy draw carries one code per microtainer. Results and documents on Get Results reference these codes via lab_code.

​
Minimum notice

Appointments at Aniva-operated locations must be booked at least 12 hours ahead; booking inside that window returns 400. Get Availability already withholds those slots, so anything you read from that grid is bookable. Locations you operate yourself have no minimum notice — same-day and walk-in booking is unchanged.

​
Duplicate appointments

A profile can hold at most one non-cancelled appointment per location and instant — one person cannot be drawn twice at one place at one moment, however many chairs the location has. Creating an appointment for a slot the profile already occupies returns 409 with an appointment_id naming the appointment that already exists:
Handle it by treating the request as already applied: fetch the appointment with Get Appointment, move it with Update Appointment, or drop it with Cancel Appointment. Do not retry the create — it will keep returning 409. This makes repeated creates safe: a request you resend after a timeout, or a double-submitted form, cannot produce two appointments for the same patient at the same time.
appointment_id is only present on the duplicate 409. The capacity 409 — the slot is full because other patients hold it — returns error alone, and the right recovery there is to pick a different slot from Get Availability.

​
Error responses