Home Kit Orders

A home kit order sends a DIY mail-home test kit to a patient. Aniva ships the kit, the patient self-collects a sample at home and mails it back. This is distinct from an appointment, which is a venous draw performed at a physical test location by a healthcare professional.

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 add panels and biomarkers, update the delivery address, cancel the order, 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, house_number, postal_code, city, country; phone / email optional). Provide exactly one — a location reference or an inline address, not both.

Show delivery address

Location reference
Inline address

string

required

UUID of the test location the kit ships to.

string

required

string

required

string

required

string

required

string

required

string

required

ISO 3166-1 alpha-2 code (two letters, e.g. DE).

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.

Show properties

string

UUID of the associated profile.

string

Patient’s first name.

string

Patient’s last name.

string

Patient’s email address.

string

Date of birth in YYYY-MM-DD format.

integer

Biological sex per ISO/IEC 5218.

object[]

Catalog panels currently attached to the home kit order. Each entry is { panel_id, added_at }. Cross-reference each 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.

Lifecycle

Home kit orders expose four lifecycle states:

pending → dispatched → activated
   │           │            │
   └───────────┴────────────┴──→ cancelled

Status	Meaning
`pending`	The order has been created but its fulfilment orders have not all been placed yet. Can be updated or cancelled; panels and biomarkers can be added or removed.
`dispatched`	All necessary fulfilment orders have been placed — the kit is on its way to (or already with) the patient. Its panel and biomarker composition is now locked (the physical kit has shipped); the order can still be cancelled.
`activated`	The patient has (supposedly) collected their sample and entered the activation code, kicking off lab processing. Terminal — analogous to `blood_drawn` on an appointment.
`cancelled`	The home kit order has been cancelled. Terminal — no further transitions.

The home kit order status surface is intentionally coarse. Delivery progression to and from the patient is tracked separately via shipments, and lab result processing via submissions — neither is part of this status enum. 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.

A home kit order’s panel and biomarker composition can only be changed while it is pending. Once the order is dispatched (or later — activated/cancelled), the /panels and /biomarkers endpoints return 409 Conflict: the physical kit ships with a fixed number of tubes derived from the selected panels and biomarkers, so its contents are frozen the moment it leaves for the patient. Attach everything you need while the order is still pending. If you do need to change the tests on an order that’s already locked, reach out to Aniva directly — it’s usually still possible, and we’ll make the change for you to keep the kit’s contents consistent.

Listing home kit orders

Retrieve all home kit orders accessible to your API key:

GET /api/v1/home-kit-orders

Optionally pass ?profile_id={uuid} to filter by a specific profile.

Creating a home kit order

Request a home kit order for a patient profile:

POST /api/v1/home-kit-orders

Pass the profile_id and a delivery_address. The order is created bare, in pending status — attach panels and biomarkers afterward with the sub-endpoints below.

Updating a home kit order

Change the delivery address of a home kit order:

PATCH /api/v1/home-kit-orders/{id}

Pass a delivery_address object to update. Only include the fields you want to change.

Cancelling a home kit order

Cancel a home kit order that is no longer needed:

DELETE /api/v1/home-kit-orders/{id}

This sets the home kit order status to cancelled. The cancelled home kit order is returned in the response.

Adding panels

Attach the catalog panels you want to run by calling:

PATCH /api/v1/home-kit-orders/{id}/panels

Pass an array of panel UUIDs in the panel_ids field. The call is idempotent — already-attached panels are kept. Panel IDs are provided by Aniva for your partner account. Panels can only be changed while the kit is pending (see Lifecycle).

Removing panels

To remove panels, call:

DELETE /api/v1/home-kit-orders/{id}/panels

Pass an array of panel UUIDs in the panel_ids field. All specified panels must currently be attached to the home kit order.

Individual biomarkers

You can attach individual biomarkers to a home kit order as à la carte tests, outside any pre-built panel. This is useful when you want a tailored selection rather than a pre-defined bundle. The attached biomarkers surface on the home kit order response as an individual_biomarkers array (siblings of panels). Add biomarkers (idempotent — already-attached biomarkers are kept):

PATCH /api/v1/home-kit-orders/{id}/biomarkers

Remove biomarkers (every ID must currently be attached, otherwise 404):

DELETE /api/v1/home-kit-orders/{id}/biomarkers

Both endpoints take a 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:

GET /api/v1/home-kit-orders/{id}/results

The response includes planned tests (status 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.

Example home kit order

{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "dispatched",
  "delivery_address": {
    "name": "Jane Doe",
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country": "DE",
    "phone": "+4930123456789",
    "email": "jane.doe@example.com"
  },
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-02T08:00:00Z",
  "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
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ]
}

Get Started

Core Concepts

Guides

Home Kit Orders

Fields

Lifecycle

Listing home kit orders

Creating a home kit order

Updating a home kit order

Cancelling a home kit order

Adding panels

Removing panels

Individual biomarkers

Retrieving lab results

Example home kit order

​Fields

​Lifecycle

​Listing home kit orders

​Creating a home kit order

​Updating a home kit order

​Cancelling a home kit order

​Adding panels

​Removing panels

​Individual biomarkers

​Retrieving lab results

​Example home kit order

Fields

Lifecycle

Listing home kit orders

Creating a home kit order

Updating a home kit order

Cancelling a home kit order

Adding panels

Removing panels

Individual biomarkers

Retrieving lab results

Example home kit order