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

# Skapa beställning av hemtestkit

> Beställ ett självtestkit med hemleverans för en profil

Begär en hemtestkitbeställning för en patientprofil. En hemtestkitbeställning skickar hem ett testkit för egenprovtagning med posten — Aniva skickar kitet till leveransadressen, patienten tar själv ett prov hemma och postar tillbaka det. Detta skiljer sig från en [bokning](https://docs.anivahealth.com/sv/api/appointments/create-appointment.md), som är en venös blodprovstagning på en provtagningsplats.

**Exakt en panel krävs.** Ett hemtestkit motsvarar 1:1 en fysisk kitprodukt — panelen är kitet — och beställningen hamnar i packkön så snart den skapas, så sammansättningen måste vara klar från början. Du kan fortfarande byta panel via [Uppdatera hemtestkitbeställning](https://docs.anivahealth.com/sv/api/home-kit-orders/update-home-kit.md) medan beställningen är `pending`.

## Ersättningskit

När ett kit inte kan leverera sina resultat — patienten kunde inte fylla röret, provet kom fram med för lite material, laboratoriet kunde inte analysera det — beställ en **ersättning** genom att skicka `replaces_home_kit_order_id`.

En ersättning är en ny beställning med en ny labbkod, även när det första kitet aldrig aktiverades: laboratoriet behöver en ny remiss, och två prover med samma kod går inte att skilja åt. Beställningen du ersätter rörs inte — den behåller sin egen status, sin egen labbkod och eventuella resultat som redan registrerats under den.

Två saker följer av det:

* **Panelen ärvs.** Utelämna `panel_id` så får ersättningen samma panel som beställningen den ersätter, vilket är det patienten köpte och hur lådan är märkt.
* **Du väljer vad som analyseras om.** Skicka `biomarker_ids` med de markörer som misslyckades så analyserar laboratoriet bara dem igen, och kitet skickas bara med de rör som behövs. Utelämna fältet för att analysera om hela panelen.

Markörer analyseras om enligt panelens grupper, inte en och en. Om du anger en markör i en grupp analyseras hela den gruppen om, eftersom det inte går att lägga en laboratoriebeställning som rapporterar mer än vad som begärts. En ersättning med en markör kan därför komma med fler än ett resultat, och antalet rör kan vara större än vad markörlistan antyder.

Bara en ersättning per kit får vara på väg åt gången.

> [!NOTE]
>
> Om du integrerade innan de här fälten fanns läser Aniva även `metadata.original_kit_id` och
> `metadata.replacement_reason` när en beställning skapas och behandlar den som en ersättning. Det
> här är det enda stället där metadata tolkas, det finns bara kvar för att stödja den tidigare
> integrationen, och fälten ovan vinner alltid. Skicka fälten.

En `201` innebär att beställningen är bekräftad och lämnas över till expediering — du behöver inte göra något mer för att kitet ska packas och skickas.

Kräver scopet `home_kit_orders_manage`.

Skicka med en valfri `Idempotency-Key`-header så att anropet säkert kan upprepas – om samma nyckel skickas igen returneras det ursprungliga svaret i stället för att en andra bokning skapas. Se [Idempotens](https://docs.anivahealth.com/sv/concepts/idempotency.md).

## Förfrågan

### Body-parametrar

**profile\_id** `string` *required*

UUID för patientprofilen som hemtestkitbeställningen ska skapas för.

**panel\_id** `string` *required*

UUID för katalogpanelen som ska beställas. Exakt en — ett hemtestkit motsvarar 1:1 en fysisk
kitprodukt, så panelen är kitet. Panel-ID:n får du från Aniva för ditt partnerkonto; se [Lista
paneler](https://docs.anivahealth.com/sv/api/panels/list-panels.md). Valfritt vid en ersättning, där den som standard får panelen
från beställningen du ersätter.

**replaces\_home\_kit\_order\_id** `string`

UUID för hemtestkitbeställningen som den här ersätter. Om du skickar det blir det här ett
ersättningskit — se [Ersättningskit](#ersaettningskit) ovan. Beställningen måste tillhöra samma
profil och får inte redan ha en ersättning på väg.

**replacement\_reason** `string`

Varför ersättningen behövs, i en mening (till exempel `Zu wenig Material, HbA1c nicht
    auswertbar`). Krävs när du skickar `replaces_home_kit_order_id` och ignoreras annars. Högst 500
tecken.

**biomarker\_ids** `integer[]`

Vid en ersättning, de markörer som laboratoriet analyserar om — normalt de som det första kitet
inte kunde leverera. Varje markör måste ingå i det som beställningen du ersätter begärde; stäm av
mot [Lista biomarkörer](https://docs.anivahealth.com/sv/api/biomarkers/list-biomarkers.md) med `home_kit=true`. Utelämna fältet för
att analysera om hela panelen. Accepteras bara tillsammans med `replaces_home_kit_order_id` och
inte tillsammans med ett annat `panel_id`. Detta kräver inget extra scope: att analysera om
markörer som patienten redan betalat för är inget à la carte-val.

**metadata** `object`

Dina egna nyckel/värde-par som returneras ordagrant vid varje läsning och aldrig tolkas av Aniva.
Använd det för att skicka med din beställningsreferens så att du kan koppla ihop dem utan att
spara våra ID:n. Högst 20 nycklar; nycklar matchar `[A-Za-z0-9_-]` och är högst 40 tecken; värden
är en sträng, ett tal eller ett booleskt värde, med strängar på högst 500 tecken; totalt 16 384
byte serialiserat. Nycklar som börjar med `aniva_` är reserverade. Lägg aldrig personuppgifter
eller kliniska data i `metadata` — det behandlas inte som patientdata.

**results\_ready\_emails** `string[]`

Upp till 5 adresser som vardera får ett mejl när alla labbresultat är klara. Mejlet länkar till
resultatsidan i Anivas adminpanel. Din nyckel behöver behörigheten `results_view` för patienten,
annars returneras `403`. Utelämna fältet för att använda standardadresserna för patientens grupp.
En tom lista stänger av mejlen. Se [Mejl när resultat är klara](https://docs.anivahealth.com/sv/concepts/results.md#mejl-naer-resultat-aer-klara).

**delivery\_address** `object` *required*

Adressen som kitet ska skickas till — i en av två former: antingen `{ location_id }` som refererar till en känd provtagningsplats, eller adressfälten direkt i objektet (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` är valfria — samma fältnamn som i locations-API:et). Ange exakt ett alternativ — en platsreferens eller en direkt adress, inte båda.

**leveransadress**

> [tab] Referera till en plats
>
> **location\_id** `string` *required*
>
> UUID för en känd provtagningsplats som kitet ska skickas till. Stäm av mot [Lista
> platser](https://docs.anivahealth.com/sv/api/locations/list-locations.md).

> [tab] Direkt adress
>
> **name** `string` *required*
>
> Mottagarens, företagets eller platsens namn.
>
> **company\_name** `string`
>
> Företag som tar emot paketet åt mottagaren — en `c/o`-mottagare eller en avdelning.
>
> **street** `string` *required*
>
> Gatunamn utan husnummer (t.ex. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Husnummer (t.ex. `118` eller `12a`).
>
> **address\_line\_2** `string`
>
> Byggnad, port eller våning.
>
> **city** `string` *required*
>
> **state** `string`
>
> Delstat eller provins. Valfritt.
>
> **postal\_code** `string` *required*
>
> Postnummer. En tysk adress (`country_code` `DE`) kräver exakt 5 siffror, t.ex. `10117`.
>
> **country\_code** `string` *required*
>
> ISO 3166-1 alpha-2-kod (två bokstäver, t.ex. `DE`). Gemener accepteras och sparas som
> versaler.
>
> **phone** `string`
>
> Mottagarens telefonnummer med landskod (t.ex. `+4791234567`). Transportören använder det för
> att meddela mottagaren om paketet, till exempel att det väntar på ett ombud. Utelämna
> fältet så får transportören inget telefonnummer.
>
> **email** `string`
>
> Mottagarens e-postadress. Transportören använder den på samma sätt som `phone`. Utelämna
> fältet så får transportören ingen e-postadress.

> [!NOTE]
>
> **Packstation eller Postfiliale (endast Tyskland):** sätt `street` till `Packstation` eller
> `Postfiliale`, `house_number` till det tresiffriga stationsnumret och `address_line_2` till
> mottagarens DHL Postnummer (6–10 siffror, mellanslag tillåtna). Utan Postnummer kan paketet inte
> bokas. Postfach stöds inte.

## Svar

Vid lyckat anrop returnerar API:et `201 Created` med den nya hemtestkitbeställningen.

**id** `string` *required*

Unik identifierare (UUID) för beställningen av hemtestkit.

**profile\_id** `string` *required*

UUID för profilen som den här beställningen av hemtestkit tillhör.

**status** `string` *required*

Nuvarande status för hemtestkitbeställningen. Ett av `pending`, `dispatched`, `activated` eller
`cancelled`. En nyskapad beställning börjar i `pending`.

**delivery\_address** `object` *required*

Adressen som kitet ska skickas till – i ett av två format: antingen `{ location_id }` som refererar till en känd testplats, eller inline-adressfälten (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` är valfria – samma fältnamn som i locations-API:et). Ange exakt ett alternativ – en platsreferens eller en inline-adress, inte båda.

**leveransadress**

> [tab] Platsreferens
>
> **location\_id** `string` *required*
>
> UUID för testplatsen som kitet skickas till.

> [tab] Inline-adress
>
> **name** `string` *required*
>
> Mottagarens, företagets eller platsens namn.
>
> **company\_name** `string`
>
> Företag som tar emot paketet åt mottagaren – en `c/o`-mottagare eller en avdelning.
>
> **street** `string` *required*
>
> Gatunamn utan husnummer (t.ex. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Husnummer (t.ex. `118` eller `12a`).
>
> **address\_line\_2** `string`
>
> Byggnad, ingång eller våning.
>
> **city** `string` *required*
>
> **state** `string`
>
> Delstat eller provins. Valfritt.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> ISO 3166-1 alpha-2-kod (två bokstäver, t.ex. `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

De nyckel/värde-par du angav. Alltid med — `{}` om du inte angav några.

**replaces\_home\_kit\_order\_id** `string`

Hemtestkitbeställningen som den här ersätter. `null` på en vanlig beställning.

**replacement\_reason** `string`

Anledningen du angav. `null` på en vanlig beställning.

**results\_ready\_emails** `string[]` *required*

Adresser som var och en får ett mejl när alla labbresultat är slutgiltiga, i gemener. Tom när funktionen är avstängd. Se
[Mejl när resultat är klara](https://docs.anivahealth.com/sv/concepts/results.md#mejl-naer-resultat-aer-klara).

**lab\_code** `string`

Laboratoriets provkod som resultaten rapporteras under – tryckt på det fysiska kitet, och det som
patienten läser av från lådan som aktiveringskod. `null` tills kitet är packat.
Skrivskyddad.

**activated\_at** `string` *required*

Tidpunkt för provtagning rapporterad via [Aktivera](https://docs.anivahealth.com/sv/api/home-kit-orders/activate-home-kit.md).
`null` tills kitet aktiveras.

**created\_at** `string` *required*

ISO 8601-tidsstämpel för när beställningen av hemtestkit skapades.

**updated\_at** `string`

ISO 8601-tidsstämpel för den senaste uppdateringen. Kan vara `null`.

**profile** `object` *required*

Patientprofilen som är kopplad till den här beställningen av hemtestkit.

**profil**

**id** `string`

Unik identifierare för profilen (UUID).

**handle** `string`

Profil-handle eller användarnamn. Kan vara `null`.

**first\_name** `string`

Förnamn. Kan vara `null`.

**last\_name** `string`

Efternamn. Kan vara `null`.

**email** `string`

E-postadress. Kan vara `null`.

**phone** `string`

Telefonnummer i E.164-format. Kan vara `null`.

**sex** `integer`

Biologiskt kön enligt ISO/IEC 5218. Kan vara `null`.

**date\_of\_birth** `string`

Födelsedatum i formatet `YYYY-MM-DD`. Kan vara `null`.

**height** `number`

Längd i centimeter. Kan vara `null`.

**weight** `number`

Vikt i kilogram. Kan vara `null`.

**language** `string`

Föredraget språk: en av de 32 koderna i [Skapa profil](https://docs.anivahealth.com/sv/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Om profilen tar emot transaktionella (programmatiska) mejl. Kan vara `null`.

**created\_at** `string`

ISO 8601-tidsstämpel för när profilen skapades.

**updated\_at** `string`

ISO 8601-tidsstämpel för den senaste uppdateringen av profilen. Kan vara `null`.

**panels** `HomeKitOrderPanel[]` *required*

Panelen som är kopplad till den här hemtestkitbeställningen — den du angav som `panel_id`, med
tidsstämpel för när beställningen skapades. Alltid exakt en. Slå upp paneldetaljer (namn,
biomarkörer) via [Lista paneler](https://docs.anivahealth.com/sv/api/panels/list-panels.md).

**Fält för kopplad panel**

**panel\_id** `string`

Panel-UUID – stäm av mot [Lista paneler](https://docs.anivahealth.com/sv/api/panels/list-panels.md).

**added\_at** `string`

ISO 8601-tidsstämpel för när panelen först kopplades till den här beställningen av hemtestkit.

**individual\_biomarkers** `HomeKitOrderIndividualBiomarker[]` *required*

Biomarkörer kopplade utanför panelen. Tom när en vanlig beställning skapas — hemtestkitbeställningar
beställs per panel, och att ändra den här listan i efterhand kräver behörighetsscopet
`home_kit_orders_individual_biomarker_selection`. Vid en ersättning innehåller den de
`biomarker_ids` du skickade, vilket är det laboratoriet analyserar om.

**Fält för enskild biomarkör**

**biomarker\_id** `integer`

Biomarköridentifierare – stäm av mot
[Lista biomarkörer](https://docs.anivahealth.com/sv/api/biomarkers/list-biomarkers.md) med `home_kit=true`.

**added\_at** `string`

ISO 8601-tidsstämpel för när biomarkören först kopplades till den här beställningen av hemtestkit.

**shipments** `HomeKitOrderShipmentLink[]` *required*

Paket kopplade till den här hemtestkitbeställningen, äldsta kopplingen först. Alltid tom när
beställningen skapas — hämta de fullständiga paketen med [Lista
försändelser](https://docs.anivahealth.com/sv/api/shipments/list-shipments.md) och `?home_kit_order_id=`.

**Fält för försändelselänk**

**id** `string`

Försändelsereferens – stäm av mot [Hämta försändelse](https://docs.anivahealth.com/sv/api/shipments/get-shipment.md).

**added\_at** `string`

ISO 8601-tidsstämpel för när försändelsen länkades till den här beställningen av hemtestkit.

## Felsvar

| Status | Beskrivning |
| - | - |
| `400` | Valideringsfel — t.ex. `delivery_address` saknar ett fält eller har ett tyskt postnummer som inte är 5 siffror, `panel_id` är inte ett giltigt UUID, eller `replacement_reason` saknas vid en ersättning. |
| `403` | Förbjudet — din API-nyckel har inte åtkomst till den här åtgärden, profilen ligger utanför ditt behörighetsscope eller så angav du `results_ready_emails` utan `results_view`-åtkomst till patienten. |
| `404` | Profilen, panelen eller hemtestkitbeställningen som ska ersättas hittades inte. |
| `409` | Konflikt — `Idempotency-Key` har redan använts med en annan body, dess ursprungliga förfrågan är inte klar ännu, eller kitet du ersätter har redan en ersättning på väg. |
| `422` | Panelen kan inte beställas som ett hemtestkit — ingen kitprodukt för expediering är konfigurerad för den. Vid en ersättning: beställningen du ersätter tillhör en annan profil, ett värde i `biomarker_ids` ingår inte i det den begärde, eller så skickade du markörer tillsammans med ett annat `panel_id`. |
| `500` | Internt serverfel. |

```bash cURL theme={null}
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"
    }
  }'
```

```bash Replacement kit theme={null}
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",
    "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "replacement_reason": "Too little material, HbA1c could not be analysed",
    "biomarker_ids": [103],
    "metadata": { "your_order_ref": "ORD-10482-R1" },
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE"
    }
  }'
```

```json 201 theme={null}
{
  "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 },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "panel_id: panel_id must be a valid UUID"
}
```

```json 404 theme={null}
{
  "error": "Profile not found"
}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.