> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Home Kit Orders

> Understand how DIY mail-home test-kit orders work in the Aniva API

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](/concepts/appointments), which is a venous draw performed at a physical test location by a healthcare professional.

<Note>
  Home kit order endpoints require the `home_kit_orders_view` (read) or `home_kit_orders_manage`
  (write) scope.
</Note>

## Fields

<ResponseField name="id" type="string" required>
  UUID auto-generated by Aniva. Use this to add panels and biomarkers, update the delivery address,
  cancel the order, and retrieve results.
</ResponseField>

<ResponseField name="profile_id" type="string" required>
  The UUID of the profile this home kit order belongs to.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current lifecycle status. One of `pending`, `dispatched`, `activated`, or `cancelled`. See
  [Lifecycle](#lifecycle) below. Lab-result completion granularity (`in_progress` vs `completed`) is
  derived from [Get Results](/api/home-kit-orders/get-results).
</ResponseField>

<ResponseField name="delivery_address" type="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.

  <Expandable title="delivery address">
    <Tabs>
      <Tab title="Location reference">
        <ResponseField name="location_id" type="string" required>
          UUID of the test location the kit ships to.
        </ResponseField>
      </Tab>

      <Tab title="Inline address">
        <ResponseField name="name" type="string" required />

        <ResponseField name="street" type="string" required />

        <ResponseField name="house_number" type="string" required />

        <ResponseField name="postal_code" type="string" required />

        <ResponseField name="city" type="string" required />

        <ResponseField name="country" type="string" required>
          ISO 3166-1 alpha-2 code (two letters, e.g. `DE`).
        </ResponseField>

        <ResponseField name="phone" type="string" />

        <ResponseField name="email" type="string" />
      </Tab>
    </Tabs>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the home kit order was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the most recent update. Null if the home kit order has never been updated.
</ResponseField>

<ResponseField name="profile" type="object">
  The full profile object for the patient, embedded in every home kit order response.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      UUID of the associated profile.
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Patient's first name.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Patient's last name.
    </ResponseField>

    <ResponseField name="email" type="string">
      Patient's email address.
    </ResponseField>

    <ResponseField name="date_of_birth" type="string">
      Date of birth in `YYYY-MM-DD` format.
    </ResponseField>

    <ResponseField name="sex" type="integer">
      Biological sex per ISO/IEC 5218.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="panels" type="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](/api/panels/list-panels).
</ResponseField>

<ResponseField name="individual_biomarkers" type="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](/api/biomarkers/list-biomarkers).
</ResponseField>

## 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](/api/home-kit-orders/update-home-kit) or [cancelled](/api/home-kit-orders/cancel-home-kit); 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.                                                                                                                                                                      |

<Note>
  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](/api/home-kit-orders/get-results) — the top-level `status` field is `in_progress`
  until every submission arrives, then `completed`.
</Note>

<Warning>
  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.
</Warning>

## 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](#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](/api/biomarkers/list-biomarkers) to discover biomarker IDs. Biomarkers can only be changed while the kit is `pending` (see [Lifecycle](#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

```json theme={null}
{
  "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"
    }
  ]
}
```