Skip to main content
POST
Request a home kit order for a patient profile. A home kit order sends a DIY mail-home test kit — Aniva ships the kit to the delivery address, the patient self-collects a sample at home and mails it back. This is distinct from an appointment, which is a venous draw at a test location. Exactly one panel is required. A home kit maps 1:1 onto a physical kit product — the panel is the kit — and the order joins the packing queue as soon as it is created, so the composition must be final up front. You can still swap the panel via Update Home Kit Order while the order is pending.

​
Replacement kits

When a kit cannot deliver its results — the patient could not fill the tube, the sample arrived with too little material, the laboratory could not analyse it — order a replacement by sending replaces_home_kit_order_id. A replacement is a new order with a new lab code, also when the first kit was never activated: the laboratory needs a new requisition, and two samples under one code cannot be told apart. The order you replace is not touched — it keeps its own status, its own lab code and any results already filed under it. Two things follow from that:
  • The panel is inherited. Leave panel_id out and the replacement carries the panel of the order it replaces, which is what the patient bought and how the box is branded.
  • You choose what is re-run. Send biomarker_ids with the markers that failed and the laboratory re-runs only those, so the kit ships only the tubes they need. Leave it out to re-run the whole panel.
Markers are re-run as the panel’s groups, not one by one. Naming one marker of a group re-runs that whole group, because a laboratory order that reports more than was asked for cannot be placed. A one-marker replacement can therefore arrive with more than one result, and its tube count can be larger than the marker list suggests. Only one replacement per kit may be on its way at a time.
If you integrated before these fields existed, Aniva also reads metadata.original_kit_id and metadata.replacement_reason on a create and treats the order as a replacement. This is the one place metadata is interpreted, it exists only to carry that earlier integration, and the fields above always win. Send the fields.
A 201 means the order is committed and will be handed to fulfilment — you don’t need to do anything else for the kit to be packed and shipped. Requires the home_kit_orders_manage scope. 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.

​
Request

​
Body parameters

​
string
required
UUID of the patient profile to create the home kit order for.
​
string
required
UUID of the catalog panel to order. Exactly one — a home kit maps 1:1 onto a physical kit product, so the panel is the kit. Panel IDs are provided by Aniva for your partner account; see List Panels. Optional on a replacement, where it defaults to the panel of the order you replace.
​
string
UUID of the home kit order this one replaces. Sending it makes this a replacement kit — see Replacement kits above. The order must belong to the same profile, and must not already have a replacement on its way.
​
string
Why the replacement is needed, in one sentence (for example Zu wenig Material, HbA1c nicht auswertbar). Required when you send replaces_home_kit_order_id, and ignored otherwise. At most 500 characters.
​
integer[]
On a replacement, the markers the laboratory re-runs — normally the ones the first kit could not deliver. Each must be part of what the order you replace asked for; cross-reference against List Biomarkers with home_kit=true. Leave it out to re-run the whole panel. Only accepted together with replaces_home_kit_order_id, and not together with a different panel_id. This needs no extra scope: re-running markers the patient already paid for is not an à-la-carte selection.
​
object
Your own key/value pairs, echoed back verbatim on every read and never interpreted by Aniva. Use it to carry your order reference so you can correlate without storing our IDs. 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. Never put personal or clinical data in metadata — it is not treated as patient data.
​
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.
​
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.
Packstation or Postfiliale (Germany only): set street to Packstation or Postfiliale, house_number to the three-digit station number, and address_line_2 to the recipient’s DHL Postnummer (6–10 digits, spaces allowed). Without the Postnummer, the parcel cannot be booked. A Postfach is not supported.

​
Response

On success, the API returns 201 Created with the new home kit order.
​
string
required
Unique home kit order identifier (UUID).
​
string
required
UUID of the profile this home kit order belongs to.
​
string
required
Current home kit order status. One of pending, dispatched, activated, or cancelled. A newly created order starts in pending.
​
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.
​
object
required
The key/value pairs you supplied. Always present — {} when you set none.
​
string
The home kit order this one replaces. null on a normal order.
​
string
The reason you supplied. null on a normal order.
​
string[]
required
Addresses that each get one email once every lab result is final, lowercased. Empty when off. See Results-ready emails.
​
string
Laboratory sample code the results report under — printed on the physical kit, and what the patient reads off the box as the activation code. null until the kit is packed. Read-only.
​
string
required
Collection timestamp reported via Activate. null until the kit is activated.
​
string
required
ISO 8601 timestamp of when the home kit order was created.
​
string
ISO 8601 timestamp of the last update. May be null.
​
object
required
The patient profile associated with this home kit order.
​
HomeKitOrderPanel[]
required
The panel attached to this home kit order — the one you supplied as panel_id, stamped with the order’s creation time. Always exactly one. Look up panel details (name, biomarkers) via List Panels.
​
HomeKitOrderIndividualBiomarker[]
required
Biomarkers attached outside the panel. Empty on a normal creation — home kit orders are ordered by panel, and modifying this list afterwards requires the home_kit_orders_individual_biomarker_selection capability scope. On a replacement it holds the biomarker_ids you sent, which are what the laboratory re-runs.
​
HomeKitOrderShipmentLink[]
required
Parcels linked to this home kit order, oldest-link first. Always empty on creation — read the full parcels with List Shipments and ?home_kit_order_id=.

​
Error responses