Home kit order endpoints require the
home_kit_orders_view (read) or home_kit_orders_manage
(write) scope.Fields
string
required
UUID auto-generated by Aniva. Use this to update the order, swap its panel, activate it, cancel
it, and retrieve results.
string
required
The UUID of the profile this home kit order belongs to.
string
required
Current lifecycle status. One of
pending, dispatched, activated, or cancelled. See
Lifecycle below. Lab-result completion granularity (in_progress vs completed) is
derived from Get Results.object
required
The address to mail the kit to — one of two shapes: either
{location_id} referencing a known
test location, or the inline address fields (name, street, city, postal_code,
country_code; company_name / house_number / address_line_2 / state / phone / email
optional — the same vocabulary as the locations API). Provide exactly one — a location reference
or an inline address, not both.string
required
ISO 8601 timestamp of when the home kit order was created.
string
ISO 8601 timestamp of the most recent update. Null if the home kit order has never been updated.
object
The full profile object for the patient, embedded in every home kit order response.
object[]
The panel attached to the home kit order — always exactly one entry of
{ panel_id, added_at },
because a home kit maps 1:1 onto a physical kit product. Cross-reference the panel_id against
List Panels.object[]
À-la-carte biomarkers attached to the home kit order outside any panel. Each entry is
{ biomarker_id, added_at }. Cross-reference each biomarker_id against
List Biomarkers.object
Your own key/value pairs, echoed back verbatim and never interpreted by Aniva. Always present on a
read —
{} when you set none. At most 20 keys; keys match [A-Za-z0-9_-] and are at most 40
characters; values are a string, number, or boolean, with strings at most 500 characters; 16384
bytes serialized overall. Keys beginning aniva_ are reserved. On
Update, metadata is merged: keys you omit survive, a
key sent as null is deleted, and {} clears everything. Validation is all-or-nothing. Never put
personal or clinical data in metadata — it is not treated as patient data and is surfaced to
fulfilment partners.string
The laboratory sample code. One code, three roles: what lab results report under, what is printed
on the physical kit, and what the patient reads off the box as the activation code. Allocated by
fulfilment at packing —
null while the order is pending, read-only always. Resolve a kit in
hand back to its order with GET /api/v1/home-kit-orders?lab_code=….string
The collection timestamp reported via Activate — when
the patient actually collected their sample, as a UTC instant.
null until the kit is activated.
This is the collection time the lab report carries.object[]
The parcels linked to this order, oldest-link first, each
{ id, added_at } — the kit on its
way to the patient and, for kits whose return leg is tracked, the sample on its way back to
the laboratory, appearing the moment fulfilment prints the labels. Empty while the order is
pending. Read the
full parcels in one call with GET /api/v1/shipments?home_kit_order_id={id} — see
Shipments.Lifecycle
Home kit orders expose four lifecycle states:The home kit order status surface is intentionally coarse. Delivery progression to and from the
patient is tracked on the order’s shipments —
dispatched means the kit
has a label and a lab code, not that it has moved; the outbound shipment’s status says whether
it has. Lab result processing lives on submissions. Lab-result completion (in_progress vs
completed) is exposed via Get Results — the top-level
status field is in_progress until every submission arrives, then completed.Tracking the parcels
destination is the lab), paired through paired_with. The
return parcel sits pending — with its tracking number already known — until the patient posts
it. A gut-microbiome kit arrives as one shipment: the kit to the patient. Its return envelope is
prepaid and untracked, so nothing is booked for the way back. Every kit parcel is booked by the
fulfilment partner (booked_by: "probatix" or "biomes"), so they are read-only here; each
carries the carrier’s full status_updates, including DHL’s detail_code for a redirect to a
post office.
Listing home kit orders
Retrieve all home kit orders accessible to your API key:?profile_id={uuid} to filter by a specific profile, or ?lab_code={code} to
resolve a physical kit in hand back to its order — the natural first step of an activation flow.
Creating a home kit order
Request a home kit order for a patient profile:profile_id, a delivery_address, and a single panel_id. The order is created in pending status.
Pass an optional Idempotency-Key header so a retry does not order a second kit — see Idempotency.
Exactly one panel, because a home kit maps 1:1 onto a physical kit product — the panel is the kit. Only panels Aniva has configured with a fulfilment kit product are orderable as home kits; an unmapped panel is rejected with 422, because without a product fulfilment cannot pack it. It is required at creation because the order reaches the fulfilment warehouse immediately and packing can start straight away. While the order is pending you can swap the panel via Update.
Updating a home kit order
Change the delivery address, swap the panel, or update your metadata:panel_id replaces the attached panel — with exactly one panel per kit, a swap is the only meaningful panel operation, which is why there are no add/remove panel endpoints. The address and the panel are mutable only while pending; metadata stays writable for the whole life of the order.
Cancelling a home kit order
Cancel a home kit order that is no longer needed:cancelled. The cancelled home kit order is returned in the response. Cancelling an order that is already cancelled returns the same 200; an activated order can no longer be cancelled and returns 409.
Activating a home kit order
When the patient has collected their sample, report it:activated_at — the moment the patient actually collected the sample, as a UTC instant. This is the collection time the lab report will carry, so send the real collection moment, not your processing time. Activation is terminal: the order moves to activated and can no longer be cancelled or changed. The home-kit counterpart of Confirm Blood Draw, without a barcode — the kit’s code is applied by fulfilment at packing, so you never need to know it.
Individual biomarkers
You can attach individual biomarkers to a home kit order as à la carte tests, outside the panel. This is useful when you want a tailored selection on top of the kit. The attached biomarkers surface on the home kit order response as anindividual_biomarkers array (a sibling of panels).
Both biomarker endpoints require the home_kit_orders_individual_biomarker_selection capability scope on top of home_kit_orders_manage — home kits are ordered by panel, so à-la-carte markers are enabled per partner. Ask Aniva if your integration needs it.
Add biomarkers (idempotent — already-attached biomarkers are kept):
404):
biomarker_ids array. Use List Biomarkers to discover biomarker IDs. Biomarkers can only be changed while the kit is pending (see Lifecycle).
Retrieving lab results
Once the lab has processed the returned sample, retrieve clinical and genetic results: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 home kit order’s lab work is done. Lab report PDFs are referenced in the documents array — use GET /api/v1/documents/{id} to download them.