Create Home Kit Order

POST

api

home-kit-orders

curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "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",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "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:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "lab_code": null,
  "activated_at": null
}

{
  "error": "panel_id: panel_id must be a valid UUID"
}

{
  "error": "Profile not found"
}

{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}

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 reaches the fulfilment warehouse 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. 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.

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

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.

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

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

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

object

required

The key/value pairs you supplied. Always present — {} when you set none.

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

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 — 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.

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 outside any panel. Always empty on creation — home kit orders are ordered by panel, and modifying this list requires the home_kit_orders_individual_biomarker_selection capability scope.

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. `delivery_address` is missing a field, or `panel_id` is not a valid UUID.
`403`	Forbidden — your API key does not have access to this operation.
`404`	Profile or panel not found.
`409`	Conflict — the `Idempotency-Key` was already used with a different body, or its original request has not completed.
`422`	The panel is not orderable as a home kit — no fulfilment kit product is configured for it.
`500`	Internal server error.

curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "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",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "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:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "lab_code": null,
  "activated_at": null
}

{
  "error": "panel_id: panel_id must be a valid UUID"
}

{
  "error": "Profile not found"
}

{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}

curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "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",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "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:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "lab_code": null,
  "activated_at": null
}

{
  "error": "panel_id: panel_id must be a valid UUID"
}

{
  "error": "Profile not found"
}

{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Units

Locations

Documents

Shipments

Create Home Kit Order

Request

Body parameters

Response

Error responses

​Request

​Body parameters

​Response

​Error responses

Request

Body parameters

Response

Error responses