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

# Individuele biomarkers toevoegen

> Voeg individuele biomarkers toe aan een afspraak

Voeg een of meer individuele biomarkers toe aan een afspraak als à-la-cartetests, buiten een
vooraf samengesteld panel. Routeringsbeslissingen worden verderop genomen door de bestellogistiek-pipeline op basis
van de mappings per lab van elke biomarker.

De resulterende set wordt synchroon gevalideerd aan de hand van de closure-regels van elk lab. Sommige biomarkers
kun je alleen verkrijgen door ze samen met andere te bestellen — een LDL/HDL-ratio wordt bijvoorbeeld
geleverd door een bestelling die ook LDL en HDL oplevert, dus alleen de ratio aanvragen is geen
coherente bestelling. (Op basis van diezelfde componenten wordt ook de *prijs* van de ratio berekend — zie het `pricing`-
overzicht bij [Biomarkers weergeven](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md).) Als de set niet correct kan worden
besteld, geeft de aanroep `400` terug met een `validation`-payload en **wordt er niets opgeslagen**, zodat je
proefondervindelijk tot een geldige set kunt komen:

1. `PATCH … { "biomarker_ids": [45] }` (alleen LDL/HDL-ratio) → `400`;
   `validation.failures[].fix_options[].add_biomarkers` vermeldt LDL en HDL.
2. `PATCH … { "biomarker_ids": [45, 43, 42] }` (ratio + LDL + HDL) → `200`.

Dezelfde lus geldt voor biomarkers die Aniva alleen binnen een positie verkoopt: vraag je er een los aan, dan geeft de aanroep
`400` terug met `error: "biomarker_requires_position"` en de posities die deze verkopen. Zie
[Prijzen](https://docs.anivahealth.com/nl/concepts/pricing.md).

[Biomarkers weergeven](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md) vermeldt sommige biomarkers als `price_cents: null`.
Deze biomarkers zijn **niet gecureerd**: Aniva heeft er geen prijs voor vastgesteld. Als je er een toevoegt, geeft de aanroep
`400` terug met `error: "biomarker_not_priced"`. Geen enkele andere biomarker lost deze fout op, omdat `null`
betekent dat je geen prijs hebt om de marker voor af te nemen. Kitmarkers zijn de uitzondering. Koppel het panel
dat de kit is, en de bijbehorende markers komen mee met het panel. De aanroep accepteert ook een bijbehorende marker die je toevoegt aan
een afspraak die dat panel al bevat.

Bij een capillaire bloedafname (`draw_method: capillary`) wordt de bloedafname verdeeld over microtainers. Panels gaan eerst, in
volgorde van boeking. Individuele biomarkers vullen daarna de vrije ruimte in de microtainers van de panels. Als ze
meer ruimte nodig hebben, openen ze nieuwe microtainers. We verdelen ze gelijkmatig. Elke microtainer bevat maximaal
150 µl aan individuele biomarkers. Een biomarker die in een eigen microtainer meer dan 150 µl nodig heeft, past
nooit, en een biomarker zonder gecureerd volume ook niet. Als de resulterende set deze regel overtreedt,
geeft de aanroep `400` terug met een `error`-melding en wordt er niets opgeslagen.

Deze aanroep is idempotent: biomarkers die al bij de afspraak staan, blijven behouden.

Vereist de scopes `appointments_schedule` en `schedule_appointments_with_individual_biomarker_selection`.

> [!WARNING]
>
> Biomarkers kunnen niet worden toegevoegd nadat je [Bloedafname
> bevestigen](https://docs.anivahealth.com/nl/api/appointments/confirm-blood-draw.md) hebt aangeroepen. Een poging om een bevestigde afspraak te wijzigen geeft
> `409 Conflict` terug.

## Verzoek

### Padparameters

**id** `string` *required*

Unieke identifier (UUID) van de afspraak.

### Bodyparameters

**biomarker\_ids** `number[]` *required*

Array van biomarker-ID's om te koppelen. Moet ten minste één item bevatten. Gebruik [Biomarkers
weergeven](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md) om ID's te vinden.

## Respons

Bij succes geeft de API `200 OK` terug als bevestiging dat de biomarkers zijn gekoppeld.

**success** `boolean`

`true` wanneer de biomarkers met succes aan de afspraak zijn toegevoegd.

### Een `400` lezen

Elke `400` voor closure-validatie of catalogus bevat een zin in `message`. Een `400` voor bodyvalidatie of
microtainers bevat alleen `error`. Vertak op `error`. Bij een
fout in de closure-validatie is `error` een zin. Bij een catalogusfout is `error` een machinecode:
`biomarker_not_priced` of `biomarker_requires_position`.

**Closure-validatie** — de set kan bij geen enkel lab correct worden besteld:

* `validation.failures[]` — alleen aanwezig bij fouten in de closure-validatie (ontbreekt bij gewone
  bodyvalidatiefouten). Eén item per biomarkergroep die geen enkel lab kan leveren, met de
  `biomarker_ids` die mislukten en `fix_options[]`, met de kleinste optie eerst. De
  `add_biomarkers` (`{ id, name }`) van elke optie is een set die je VOLLEDIG toevoegt — behoud je oorspronkelijke selectie, voeg deze toe en
  probeer het opnieuw. Een lege `fix_options` betekent dat iets toevoegen niet helpt; verwijder in plaats daarvan de biomarker.

**Biomarker zonder prijs** — Aniva heeft geen prijs vastgesteld voor deze biomarker. [Biomarkers
weergeven](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md) vermeldt deze als `price_cents: null`, of laat deze weg als het
een ratio is met een component zonder prijs. `error` is `biomarker_not_priced` en `biomarker_id` noemt
de marker. Geen enkele andere biomarker lost deze fout op, dus verwijder de biomarker. Twee voorwaarden maken een
biomarker bestelbaar: een lab waarnaar Aniva kan routeren moet deze leveren **en** de Aniva-catalogus moet er een prijs voor
bevatten.

**Afgeschermde biomarker** — een biomarker die alleen binnen een positie wordt verkocht, zonder dekkende positie in de
set. `error` is `biomarker_requires_position`, `biomarker_id` noemt de marker en `positions[]`
vermeldt elke positie die deze verkoopt, goedkoopste eerst. Voeg elke biomarker van een daarvan toe. Zie
[Prijzen](https://docs.anivahealth.com/nl/concepts/pricing.md) voor het model en `pricing.positions` bij [Biomarker
ophalen](https://docs.anivahealth.com/nl/api/biomarkers/get-biomarker.md) voor de volledige set markers van een positie.

## Foutresponsen

| Status | Beschrijving |
| - | - |
| `400` | `biomarker_ids` is leeg of bevat geen gehele getallen, de set faalt voor de closure-validatie (`validation.failures`), voegt een biomarker toe waarvoor Aniva geen prijs heeft vastgesteld (`error: "biomarker_not_priced"`), bevat een afgeschermde biomarker die door geen enkele positie in de set wordt gedekt (`error: "biomarker_requires_position"`), of bij een capillaire bloedafname passen de biomarkers niet in hun microtainers. |
| `403` | Forbidden — ontbrekende scope of afspraak buiten de toegangscontext. |
| `404` | Afspraak of een of meer biomarkers niet gevonden. |
| `409` | Conflict — biomarkers kunnen niet worden gewijzigd nadat de bloedafname is bevestigd. |
| `500` | Interne serverfout. |

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/biomarkers \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "biomarker_ids": [45, 43, 42]
  }'
```

```json 200 theme={null}
{
  "success": true
}
```

```json 400 (closure validation) theme={null}
{
  "error": "LDL / HDL Ratio cannot be ordered cleanly with this set — add LDL Cholesterol / HDL Cholesterol (see validation.failures for every option).",
  "message": "LDL / HDL Ratio cannot be ordered cleanly with this set — add LDL Cholesterol / HDL Cholesterol (see validation.failures for every option).",
  "validation": {
    "failures": [
      {
        "biomarker_ids": [45],
        "fix_options": [
          {
            "add_biomarkers": [
              { "id": 43, "name": "LDL Cholesterol" },
              { "id": 42, "name": "HDL Cholesterol" }
            ]
          }
        ]
      }
    ]
  }
}
```

```json 400 (biomarker Aniva has not priced) theme={null}
{
  "error": "biomarker_not_priced",
  "message": "Adrenaline, 24h urine carries no price in the catalog you can order from — GET /api/v1/biomarkers/1465 reports price_cents: null for it, and a marker with no price cannot be ordered.",
  "biomarker_id": 1465
}
```

```json 400 (biomarker sold only inside a position) theme={null}
{
  "error": "biomarker_requires_position",
  "message": "Mean Platelet Volume (MPV) is not sold on its own — it comes only inside a position. Add every biomarker of one of the positions listed here; the cheapest is \"Blood Count (extended)\".",
  "biomarker_id": 77,
  "positions": [
    {
      "id": "3f1a8c22-64bd-4e57-8a90-1c2d3e4f5a6b",
      "name": "Blood Count (extended)",
      "price_cents": 460,
      "retail_cents": 529
    }
  ]
}
```

```json 400 (capillary, does not fit) theme={null}
{
  "error": "Some individual biomarkers need more than 150 µl of one lab's microtainer. Remove some of them."
}
```

```json 409 theme={null}
{
  "error": "Individual biomarkers cannot be modified after blood draw has been confirmed"
}
```

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


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