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

# Luo profiili

> Luo uusi potilasprofiili ja liitä se profiiliryhmään

Luo uusi potilasprofiili ja liitä se profiiliryhmään. Profiili sisältää demografiset tiedot, joita käytetään ajanvarauksissa ja laboratoriotilauksissa.

Vaatii `create_user`-oikeuden.

Lähetä valinnainen `Idempotency-Key`-otsikko, jotta luontipyynnön voi yrittää turvallisesti uudelleen — saman avaimen toistaminen palauttaa alkuperäisen vastauksen toisen luomisen sijaan. Katso [Idempotenssi](https://docs.anivahealth.com/fi/concepts/idempotency.md).

## Pyyntö

### Runkoparametrit

**first\_name** `string` *required*

Potilaan etunimi. On käytettävä latinalaisia merkkejä, 1–100 merkkiä.

**last\_name** `string` *required*

Potilaan sukunimi. On käytettävä latinalaisia merkkejä, 1–100 merkkiä. Laboratoriot hylkäävät
tilaukset potilailta, joilla ei ole sukunimeä, joten profiilia ei voi luoda ilman sitä.

Kolme arvoa on varattu testiaineiston alustamiseen — katso [Sandbox-testiaineistot](#sandbox-testiaineistot).

**sex** `integer` *required*

Biologinen sukupuoli standardin ISO/IEC 5218 mukaisesti. Käytä arvoa `1` miehelle ja `2` naiselle.
Laboratorio tarvitsee sen viitealueita varten, joten `0` (tuntematon) palauttaa `400`. Pakollinen,
ellei profiiliryhmäsi anna potilaan syöttää sitä pakkauksen aktivointisivulla. Jätä se silloin
pois. Katso
[Anna potilaan syöttää syntymäaika ja sukupuoli](https://docs.anivahealth.com/fi/concepts/profiles.md#anna-potilaan-syoettaeae-syntymaeaika-ja-sukupuoli).

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

Syntymäaika muodossa `YYYY-MM-DD`. Täytyy olla menneisyydessä eikä ennen vuotta 1900. Lasketun iän
on oltava 16–100 vuotta. Muut arvot palauttavat `400`. Pakollinen, ellei profiiliryhmäsi anna
potilaan syöttää sitä pakkauksen aktivointisivulla. Jätä se silloin pois.

**profile\_group** `string` *required*

Polymorfinen viittaus (UUID tai slug) profiiliryhmään, johon tämä profiili liitetään. UUID on
muuttumaton tunniste, joka säilyy slugin uudelleennimeämisistä huolimatta; slug hyväksytään
edelleen markkinointi- ja kumppani-integraatioissa, jotka perustuvat luettaviin tunnisteisiin.
UUID on suositeltavampi. Profiiliryhmän on oltava API-avaimesi käyttöoikeusalueella. Pakollinen,
ellet lähetä vanhentunutta kenttää `profile_group_slug`.

**profile\_group\_slug** `string` *deprecated*

Vanhentunut: käytä kenttää `profile_group`. Profiiliryhmän slug. Vain pieniä kirjaimia, numeroita,
yhdysmerkkejä ja alaviivoja.

**email** `string`

Profiilin sähköpostiosoite. Jos jätetään pois, Aniva luo sähköpostiosoitteen automaattisesti.

Kentän `email` antaminen tekee luonnista myös **uudelleenyrityksille turvallisen**: yhdellä
osoitteella voi olla vain yksi profiili, joten toistuva pyyntö palauttaa `409` toisen profiilin
sijaan. Automaattisesti luodut osoitteet ovat yksilöllisiä pyyntöä kohden. Lähetä `email` tai
`Idempotency-Key`, jos integraatiosi tekee uudelleenyrityksiä.

**phone** `string`

Puhelinnumero E.164-muodossa (esim. `+14155552671`).

**height** `number`

Pituus senttimetreinä.

**weight** `number`

Paino kilogrammoina.

**language** `string` (default: en)

Profiilin ensisijainen kieli: `en`, `bg`, `ca`, `cs`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`, `ga`, `hr`, `hu`, `is`, `it`, `lb`, `lt`, `lv`, `mt`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `tr` tai `uk`. Oletusarvo on `en`.

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

Saako tämä profiili tapahtumapohjaisia (ohjelmallisia) sähköposteja — ajanvarausvahvistuksia,
ilmoituksia valmistuneista tuloksista jne. Ohittaa profiiliryhmän oletuksen. Erillinen
markkinointiluvasta. Jätä pois käyttääksesi oletusta.

**marketing\_emails\_enabled** `boolean`

Suostuuko tämä profiili markkinointisähköposteihin (uutiskirjeet, tuotepäivitykset). Ohittaa
profiiliryhmän oletuksen. Erillinen tapahtumapohjaisista sähköposteista. Jätä pois käyttääksesi
profiiliryhmän oletusta. Vain kirjoitettava: ei palauteta profiilivastauksessa.

## Sandbox-testiaineistot

Jokainen testaamisen arvoinen lukupolku — [Listaa ajanvaraukset](https://docs.anivahealth.com/fi/api/appointments/list-appointments.md),
[Hae tulokset](https://docs.anivahealth.com/fi/api/appointments/get-results.md),
[Lataa asiakirja](https://docs.anivahealth.com/fi/api/documents/download-document.md) — on tyhjä, kunnes varsinainen verinäytteenotto
tapahtuu päiviä myöhemmin. Se tekee automatisoidun integraatiotestin kirjoittamisesta hankalaa.

Kolme `last_name`-arvoa on varattu tämän ratkaisemiseksi. Luo profiili jollakin niistä, niin Aniva
esitäyttää alla kuvatun tilan ennen vastaamista, jolloin seuraava kutsusi näkee sen jo:

| `last_name` | Mitä profiili saa |
| - | - |
| `Upcomingtestmann` | Yksi tuleva `confirmed`-ajanvaraus, johon on liitetty paneeli. Ei vielä tuloksia. |
| `Partialtestmann` | Yksi mennyt `blood_drawn`-ajanvaraus. Noin **puolet** paneelista on raportoitu; [Hae tulokset](https://docs.anivahealth.com/fi/api/appointments/get-results.md) on tilassa `in_progress`. |
| `Fulltestmann` | Yksi mennyt `blood_drawn`-ajanvaraus. Paneelin **jokainen** biomarkkeri on raportoitu, `status: "completed"`, sekä laboratorioraportin PDF kentässä `documents[]`. |

Vertailu ei huomioi kirjainkokoa. Kaikki muut kentät — mukaan lukien `date_of_birth` ja `sex` —
tallennetaan ja käytetään normaalisti, joten saamasi viitealueet ovat luomasi profiilin todelliset
ikä- ja sukupuolikohtaiset viitealueet.

Ajanvaraus tehdään **Aniva Test** -toimipisteeseen todelliselle varattavalle ajalle vähintään viiden päivän
päähän (tai viisi päivää taaksepäin menneissä tiloissa). Sen alustaminen ei tee laboratoriotilausta eikä varaa
kuriiria.

> [!NOTE]
>
> Anna testiprofiileille hallinnoimasi osoite. Anivan ajanvarausmuistutukset perustuvat
> `scheduled_at`-arvoon, joten tuleva testiaineisto lähettää niitä, ellei profiilin asetuksena ole
> `transactional_emails_enabled: false`.

Paneeli valitaan satunnaisesti niistä, jotka API-avaimesi näkee, joten sen `panel_id` löytyy aina
[Listaa paneelit](https://docs.anivahealth.com/fi/api/panels/list-panels.md) -päätepisteestäsi. Kliiniset biomarkkerit saavat arvon
biomarkkerin viitealueelta; geenit saavat satunnaisen genotyypin Anivan viitedatasta, ja vastaavat variantit, kliininen merkitys sekä rs-tunnisteet määräytyvät sen perusteella.

> [!NOTE]
>
> Paneeli ja arvot luodaan uudelleen jokaisella kerralla, joten tarkista rakenne tietyn
> paneelin tai tarkkojen lukujen sijaan.

## Vastaus

Onnistuessaan API palauttaa tilan `201 Created` ja juuri luodun profiilin.

**id** `string` *required*

Profiilin yksilöllinen tunniste (UUID).

**handle** `string`

Profiilin nimimerkki tai käyttäjätunnus. Voi olla `null`.

**first\_name** `string`

Etunimi. Voi olla `null`.

**last\_name** `string`

Sukunimi. Voi olla `null`.

**email** `string`

Sähköpostiosoite. Voi olla `null`.

**phone** `string`

Puhelinnumero E.164-muodossa. Voi olla `null`.

**sex** `integer`

Biologinen sukupuoli ISO/IEC 5218 -standardin mukaan (`0` = tuntematon, `1` = mies, `2` = nainen). Voi olla `null`.

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

Syntymäaika `YYYY-MM-DD`-muodossa. Voi olla `null`.

**height** `number`

Pituus senttimetreinä. Voi olla `null`.

**weight** `number`

Paino kilogrammoina. Voi olla `null`.

**language** `string`

Ensisijainen kieli, yksi yllä olevista 32 koodista.

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

Vastaanottaako profiili tapahtumapohjaisia (ohjelmallisia) sähköposteja. `null`, jos arvoa ei ole koskaan asetettu.

**created\_at** `string`

ISO 8601 -aikaleima profiilin luontihetkestä.

**updated\_at** `string`

ISO 8601 -aikaleima viimeisimmästä päivityksestä. `null` vasta luoduilla profiileilla.

## Virhevastaukset

| Tila | Kuvaus |
| - | - |
| `400` | Validointivirhe — yksi tai useampi kenttä ei läpäissyt validointia. |
| `403` | Kielletty — API-avaimellasi ei ole oikeutta tähän toimintoon tai profiiliryhmä on käyttöoikeusalueesi ulkopuolella. |
| `404` | Profiiliryhmää ei löytynyt. |
| `409` | Annetulla `email`-osoitteella on jo profiili (vastaus sisältää osoitteen) tai samalle henkilölle on jo profiili (katso alla), tai `Idempotency-Key`-avainta käytettiin uudelleen eri pyynnön rungolla, tai alkuperäinen pyyntö ei ole vielä valmistunut. |
| `500` | Palvelimen sisäinen virhe. |

Tilakoodi `409` näyttää tältä — käsittele se merkkinä siitä, että profiili on jo olemassa, ja hae se
[Listaa profiilit](https://docs.anivahealth.com/fi/api/profiles/list-profiles.md) -päätepisteellä (`?email=`) sen sijaan, että yrittäisit luontia uudelleen:

```json theme={null}
{
  "error": "An account with the email \"maria.schmidt@example.com\" already exists.",
  "error_name": "email_exists_error",
  "email": "maria.schmidt@example.com"
}
```

Henkilö, jolla on sama etunimi, sukunimi, sukupuoli ja syntymäaika kuin avaimellesi näkyvällä profiililla,
saa vastauksen `409` ja arvon `error_name: "duplicate_profile_error"`. Käytä palautettua `profile_id`-arvoa toisen
profiilin luomisen sijaan:

```json theme={null}
{
  "error": "A patient named \"Maria Schmidt\", born 02-04-1990, with the same biological sex already exists as m***@example.com. Search for that patient and select them instead of creating a duplicate.",
  "error_name": "duplicate_profile_error",
  "profile_id": "3f1c2a8e-5b7d-4c9e-8a21-6d4f0b9e7c35",
  "full_name": "Maria Schmidt",
  "date_of_birth": "1990-04-02",
  "masked_email": "m***@example.com"
}
```

Testidataa alustavat sandbox-sukunimet ovat tästä poikkeus.

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/profiles \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Maria",
    "last_name": "Schmidt",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "profile_group": "acme-clinic-berlin",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "marketing_emails_enabled": false
  }'
```

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

```json 400 theme={null}
{
  "error": "date_of_birth: Birthdate cannot be in the future."
}
```

```json 404 theme={null}
{
  "error": "Profile group 'acme-clinic-berlin' not found"
}
```


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