Update Home Kit Order

PATCH

api

home-kit-orders

{id}

curl --request PATCH \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Unter den Linden",
      "house_number": "77",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'

{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "street": "Unter den Linden",
    "house_number": "77",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": "2026-04-01T13:10:00Z",
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:50:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482" },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}

{
  "error": "delivery_address: Invalid input"
}

{
  "error": "Panels and biomarkers can only be changed while the home kit order is pending. Once it is dispatched, activated, or cancelled its composition is locked."
}

{
  "error": "Home kit order not found"
}

Update a home kit order’s delivery address, panel, metadata, or results-ready emails. Only include the fields you want to change. The delivery address and the panel can only be changed while the order is pending, because the physical kit ships at dispatch. metadata is your own bookkeeping and stays writable for the whole life of the order. There are no add/remove panel endpoints: a home kit carries exactly one panel (it maps 1:1 onto a physical kit product), so the only meaningful panel operation is the swap you do here. Requires the home_kit_orders_manage scope.

Request

Path parameters

string

required

Unique identifier (UUID) of the home kit order to update.

Body parameters

All body parameters are optional — only include the fields you want to change.

object

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.

Show delivery address

Reference a location
Inline address

string

required

UUID of a known test location to ship the kit to. Correlate with List Locations.

string

required

Recipient, company, or location name.

string

Company holding the parcel for the recipient — a c/o party or a department.

string

required

Street name, without the house number (e.g. Wilhelmstraße).

string

House number (e.g. 118 or 12a).

string

Building, entrance, or floor.

string

required

string

State or province. Optional.

string

required

string

required

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

string

Recipient’s phone number, with country code (e.g. +4791234567). The carrier uses it to tell the recipient about the parcel, for example that it waits at a pickup point. Leave it out and the carrier gets no phone number.

string

Recipient’s email. The carrier uses it like phone. Leave it out and the carrier gets no email.

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.

string

UUID of the panel to attach in place of the current one — with exactly one panel per kit, a swap is the only meaningful operation. Only while the order is pending, and only to a panel Aniva has configured with a fulfilment kit product (422 otherwise); a swap to the already-attached panel is a no-op.

object

Your own key/value pairs. Merged into the existing metadata rather than replacing it: keys you omit are preserved, a key sent with a null value is deleted, and an empty object {} clears everything. Limits match Create Home Kit Order, and validation is all-or-nothing — if any key is rejected, nothing is written. Never put personal or clinical data in metadata — it is not treated as patient data.

string[]

Replaces the list of up to 5 addresses that each get one email once every lab result is final. Send [] to turn the emails off. Editable in every status except cancelled. Your key needs results_view access to the patient, else 403. See Results-ready emails.

Response

On success, the API returns 200 OK with the updated home kit order and its embedded profile.

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.

object

required

Show delivery address

Location reference
Inline address

string

required

UUID of the test location the kit ships to.

string

required

Recipient, company, or location name.

string

Company holding the parcel for the recipient — a c/o party or a department.

string

required

Street name, without the house number (e.g. Wilhelmstraße).

string

House number (e.g. 118 or 12a).

string

Building, entrance, or floor.

string

required

string

State or province. Optional.

string

required

string

required

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

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 — when the patient collected their sample. null until the kit is activated.

string

The home kit order this one replaces, when it is a replacement kit. null on a normal order. See Create Home Kit Order.

string

Why the replacement was sent. 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.

object

required

Partner-defined key/value pairs, echoed back verbatim. Always present — {} when unset.

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.

Show profile

string

Unique profile identifier (UUID).

string

Profile handle or username. May be null.

string

First name. May be null.

string

Last name. May be null.

string

Email address. May be null.

string

Phone number in E.164 format. May be null.

integer

Biological sex per ISO/IEC 5218. May be null.

string

Date of birth in YYYY-MM-DD format. May be null.

number

Height in centimeters. May be null.

number

Weight in kilograms. May be null.

string

Preferred language (en, de, or fi).

boolean

Whether this profile receives transactional (programmatic) emails. May be null.

string

ISO 8601 timestamp of when the profile was created.

string

ISO 8601 timestamp of the last profile update. May be null.

HomeKitOrderPanel[]

required

The panel attached to this home kit order — always exactly one (a home kit maps 1:1 onto a physical kit product), replaced in place when you pass panel_id. Look up panel details (name, biomarkers) via List Panels.

Show Panel attachment fields

string

Panel UUID — cross-reference against List Panels.

string

ISO 8601 timestamp the panel was first attached to this home kit order.

HomeKitOrderIndividualBiomarker[]

required

À-la-carte biomarkers attached to this home kit order outside any panel. Cross-reference each biomarker_id against List Biomarkers with home_kit=true for display data.

Show Individual biomarker fields

integer

Biomarker identifier — cross-reference against List Biomarkers with home_kit=true.

string

ISO 8601 timestamp the biomarker was first attached to this home kit order.

HomeKitOrderShipmentLink[]

required

Parcels linked to this home kit order, oldest-link first — normally the kit to the patient and the sample back to the laboratory. Empty until fulfilment prints a label. Read the full parcels with List Shipments and ?home_kit_order_id=.

Show Shipment link fields

string

Shipment reference — cross-reference against Get Shipment.

string

ISO 8601 timestamp the shipment was linked to this home kit order.

Error responses

Status	Description
`400`	Validation error — e.g., invalid UUID format or a missing `delivery_address` field.
`403`	Forbidden — your API key does not have access to this operation, the home kit order is outside your permission scope, or you set `results_ready_emails` without `results_view` access to the patient.
`404`	Home kit order not found, or the `panel_id` panel does not exist.
`409`	Conflict — the order is no longer `pending`; address and panel can only change before dispatch.
`409`	Conflict — the order is a replacement kit, which keeps the panel of the order it replaces.
`409`	Conflict — the order is `cancelled` and you sent `results_ready_emails`.
`422`	The panel is not orderable as a home kit — no fulfilment kit product is configured.
`500`	Internal server error.

curl --request PATCH \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Unter den Linden",
      "house_number": "77",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'

{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "street": "Unter den Linden",
    "house_number": "77",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": "2026-04-01T13:10:00Z",
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:50:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482" },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}

{
  "error": "delivery_address: Invalid input"
}

{
  "error": "Panels and biomarkers can only be changed while the home kit order is pending. Once it is dispatched, activated, or cancelled its composition is locked."
}

{
  "error": "Home kit order not found"
}

curl --request PATCH \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Unter den Linden",
      "house_number": "77",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'

{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "street": "Unter den Linden",
    "house_number": "77",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": "2026-04-01T13:10:00Z",
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:50:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482" },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}

{
  "error": "delivery_address: Invalid input"
}

{
  "error": "Panels and biomarkers can only be changed while the home kit order is pending. Once it is dispatched, activated, or cancelled its composition is locked."
}

{
  "error": "Home kit order not found"
}

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Pricing

Units

Locations

Documents

Shipments

Webhooks

Request

Path parameters

Body parameters

Response

Error responses

​Request

​Path parameters

​Body parameters

​Response

​Error responses

Request

Path parameters

Body parameters

Response

Error responses