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" },
  "lab_code": null,
  "activated_at": null
}

{
  "error": "delivery_address.postal_code is required"
}

{
  "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, or metadata. 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

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 and is surfaced to fulfilment partners.

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 fulfilment packs the kit. Read-only.

string

required

Collection timestamp reported via Activate — when the patient collected their sample. null until the kit is activated.

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 for display data.

Show Individual biomarker fields

integer

Biomarker identifier — cross-reference against List Biomarkers.

string

ISO 8601 timestamp the biomarker was first attached 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.
`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.
`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" },
  "lab_code": null,
  "activated_at": null
}

{
  "error": "delivery_address.postal_code is required"
}

{
  "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" },
  "lab_code": null,
  "activated_at": null
}

{
  "error": "delivery_address.postal_code is required"
}

{
  "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

Units

Locations

Documents

Shipments

Update Home Kit Order

Request

Path parameters

Body parameters

Response

Error responses

​Request

​Path parameters

​Body parameters

​Response

​Error responses

Request

Path parameters

Body parameters

Response

Error responses