Appointments
Confirm Blood Draw
Record that blood has been drawn and trigger the lab order pipeline
POST
/
api
/
v1
/
appointments
/
{id}
/
confirm
curl --request POST \
--url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/confirm \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"lab_code": "7642001234"
}'
curl --request POST \
--url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/confirm \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"lab_codes": [
{ "lab_code": "7642001234", "panel_ids": ["f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d"] },
{ "lab_code": "7642001235", "panel_ids": ["0a9b8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d"] }
]
}'
{
"success": true
}
{
"error": "lab_codes: Provide exactly one of `lab_code` or `lab_codes`"
}
{
"error": "Appointment not found"
}
{
"error": "This barcode has already been assigned to another patient. Please use a different tube.",
"reason": "already_assigned",
"lab_code": "7642001235"
}
{
"error": "Barcode 7642001236 carries no panel and no biomarker.",
"reason": "panel_coverage",
"lab_code": null
}
{
"error": "Recording a blood draw is only available on the appointment day (Oct 13, 2026). Reschedule the appointment to today, then confirm.",
"reason": "appointment_not_today",
"lab_code": null
}
Record that a blood draw has been completed and trigger the lab order pipeline. Submit the lab codes (tube barcodes) from the blood draw kit to link the physical samples to the appointment.
A draw carries its codes in one of two ways:
The recorded codes are returned as
- One code for the whole draw — a venous draw, where the same barcode is printed on every tube. Send it as
lab_code. - One code per microtainer — a pharmacy draw, where each microtainer has its own barcode. Send them as
lab_codes, one entry per code with thepanel_idsits microtainer holds. Each code becomes its own laboratory requisition — the barcode on the tube is the lab’s order number. An entry withoutpanel_idsis a catch-all for every panel not named elsewhere. A venous draw has at most one.
panel_ids for each microtainer they need on their own, and no more. A code that ends up with no panel and no biomarker is refused with 409 and reason: "panel_coverage". Every code is validated before anything is written; if any code cannot be used or a panel is left uncovered, nothing is recorded and the response names the problem.
Requires the test_sessions_schedule scope.
This action is irreversible. Once you confirm the blood draw, the appointment is locked — no
further modifications, including adding panels, are possible.
Request
Path parameters
string
required
Unique identifier (UUID) of the appointment to confirm.
Body parameters
string
Numeric lab code printed on the blood draw kit, when one code covers every tube. Mutually
exclusive with
lab_codes.object[]
Every lab code of the draw, in scan order (at least one entry). Mutually exclusive with
lab_code. A
code may appear only once; a panel may be named on one entry only.Show lab code entry
Show lab code entry
string
required
Numeric lab code printed on the tubes of these panels.
string[]
The attached panels whose tubes carry this code —
panel_id values from the appointment’s
panels. Omit or send [] for the catch-all covering every panel not named elsewhere plus
the à-la-carte biomarkers. A venous draw has at most one catch-all. At a pharmacy, a catch-all
holds à-la-carte biomarkers only, and you send one per microtainer they need.Response
On success, the API returns200 OK confirming the lab order pipeline has been triggered.
boolean
true when the blood draw has been recorded and the lab order pipeline triggered.string
Present only when the draw was recorded on a day other than the appointment day. Ordinary keys
cannot do this — they get a
409 with reason: "appointment_not_today". Reschedule the
appointment to the day of the draw, then confirm.lab_codes on Get Appointment, and every result and document on Get Results carries the lab_code it was filed under.
Error responses
| Status | Description |
|---|---|
400 | Validation error — neither or both of lab_code and lab_codes given, a code is not numeric, or a code or panel is repeated. |
403 | Forbidden — your API key does not have access to this operation. |
404 | Appointment not found. |
409 | A code cannot be used (reason: unregistered, already_assigned, home_kit_code, location_unknown, cross_location), a panel is left without a code, a panel_id is not attached, a venous draw has two entries without panel_ids, a pharmacy draw has more entries without panel_ids than microtainers, or a pharmacy code does not match its microtainers (all panel_coverage), or the appointment is not confirmable (session_cancelled, session_already_drawn, session_not_ready, appointment_not_today). lab_code names the code where one is at fault. |
500 | Internal server error. |
curl --request POST \
--url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/confirm \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"lab_code": "7642001234"
}'
curl --request POST \
--url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/confirm \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"lab_codes": [
{ "lab_code": "7642001234", "panel_ids": ["f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d"] },
{ "lab_code": "7642001235", "panel_ids": ["0a9b8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d"] }
]
}'
{
"success": true
}
{
"error": "lab_codes: Provide exactly one of `lab_code` or `lab_codes`"
}
{
"error": "Appointment not found"
}
{
"error": "This barcode has already been assigned to another patient. Please use a different tube.",
"reason": "already_assigned",
"lab_code": "7642001235"
}
{
"error": "Barcode 7642001236 carries no panel and no biomarker.",
"reason": "panel_coverage",
"lab_code": null
}
{
"error": "Recording a blood draw is only available on the appointment day (Oct 13, 2026). Reschedule the appointment to today, then confirm.",
"reason": "appointment_not_today",
"lab_code": null
}
⌘I
curl --request POST \
--url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/confirm \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"lab_code": "7642001234"
}'
curl --request POST \
--url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/confirm \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"lab_codes": [
{ "lab_code": "7642001234", "panel_ids": ["f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d"] },
{ "lab_code": "7642001235", "panel_ids": ["0a9b8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d"] }
]
}'
{
"success": true
}
{
"error": "lab_codes: Provide exactly one of `lab_code` or `lab_codes`"
}
{
"error": "Appointment not found"
}
{
"error": "This barcode has already been assigned to another patient. Please use a different tube.",
"reason": "already_assigned",
"lab_code": "7642001235"
}
{
"error": "Barcode 7642001236 carries no panel and no biomarker.",
"reason": "panel_coverage",
"lab_code": null
}
{
"error": "Recording a blood draw is only available on the appointment day (Oct 13, 2026). Reschedule the appointment to today, then confirm.",
"reason": "appointment_not_today",
"lab_code": null
}