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

# Profil erstellen

> Ein neues Patientenprofil erstellen und einer Profilgruppe zuweisen

Erstelle ein neues Patientenprofil und weise es einer Profilgruppe zu. Das Profil enthält demografische Daten, die für Termine und Laboraufträge verwendet werden.

Erfordert den Scope `create_user`.

Sende einen optionalen `Idempotency-Key`-Header, damit sich das Erstellen sicher wiederholen lässt – bei Wiederholung mit demselben Schlüssel kommt die ursprüngliche Antwort zurück, statt einen zweiten Termin zu erstellen. Siehe [Idempotenz](https://docs.anivahealth.com/de/concepts/idempotency.md).

## Anfrage

### Body-Parameter

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

Vorname des Patienten. Muss lateinische Zeichen verwenden, zwischen 1 und 100 Zeichen.

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

Nachname des Patienten. Muss lateinische Zeichen verwenden, zwischen 1 und 100 Zeichen. Labore
lehnen Aufträge für Patienten ohne Nachnamen ab, daher kann kein Profil ohne Nachnamen erstellt
werden.

Drei Werte sind für vordefinierte Testdaten reserviert – siehe [Sandbox-Testdaten](#sandbox-testdaten).

**sex** `integer` *required*

Biologisches Geschlecht nach ISO/IEC 5218. Verwende `1` für männlich, `2` für weiblich. Das Labor
benötigt es für die Referenzbereiche, daher gibt `0` (unbekannt) `400` zurück. Erforderlich, es
sei denn, deine Profilgruppe lässt Patienten es auf der Kit-Aktivierungsseite eingeben. Lass es
dann weg. Siehe
[Patienten Geburtsdatum und Geschlecht eingeben lassen](https://docs.anivahealth.com/de/concepts/profiles.md#geburtsdatum-und-geschlecht-vom-patienten-eingeben-lassen).

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

Geburtsdatum im Format `YYYY-MM-DD`. Muss in der Vergangenheit liegen und darf nicht vor 1900
sein. Das sich daraus ergebende Alter muss zwischen 16 und 100 liegen. Andere Werte geben `400`
zurück. Erforderlich, es sei denn, deine Profilgruppe lässt Patienten es auf der
Kit-Aktivierungsseite eingeben. Lass es dann weg.

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

Polymorphe Referenz (UUID oder Slug) auf die Profilgruppe, der dieses Profil zugewiesen wird.
Die UUID ist die unveränderliche Kennung und bleibt auch bei Umbenennungen des Slugs gültig; der
Slug wird weiterhin für Marketing- und Partnerintegrationen mit lesbaren Kennungen akzeptiert.
Die UUID wird bevorzugt. Die Profilgruppe muss im Zugriffskontext deines API-Schlüssels liegen.
Erforderlich, sofern du nicht das veraltete Feld `profile_group_slug` sendest.

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

Veraltet: Verwende `profile_group`. Slug der Profilgruppe. Nur Kleinbuchstaben, Ziffern,
Bindestriche und Unterstriche.

**email** `string`

E-Mail-Adresse für das Profil. Wenn weggelassen, generiert Aniva automatisch eine E-Mail-Adresse.

Die Angabe von `email` macht das Erstellen außerdem **wiederholungssicher**: Eine Adresse kann
immer nur ein Profil haben, sodass eine wiederholte Anfrage `409` statt eines zweiten Profils
zurückgibt. Automatisch generierte Adressen sind pro Anfrage eindeutig. Sende `email` oder einen
`Idempotency-Key`, wenn deine Integration Anfragen wiederholt.

**phone** `string`

Telefonnummer im E.164-Format (z. B. `+14155552671`).

**height** `number`

Körpergröße in Zentimetern.

**weight** `number`

Gewicht in Kilogramm.

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

Bevorzugte Sprache für das Profil: `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` oder `uk`. Standardwert ist `en`.

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

Ob dieses Profil transaktionale (programmatische) E-Mails erhalten soll – Terminbestätigungen,
Benachrichtigungen über vorliegende Ergebnisse usw. Überschreibt den Standard der Profilgruppe.
Unabhängig vom Marketing-Opt-in. Weglassen, um den Standard zu verwenden.

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

Ob dieses Profil Marketing-E-Mails (Newsletter, Produktupdates) zustimmt. Überschreibt den
Standard der Profilgruppe. Unabhängig von transaktionalen E-Mails. Weglassen, um den Standard der
Profilgruppe zu verwenden. Nur schreibbar: wird in der Profil-Antwort nicht zurückgegeben.

## Sandbox-Testdaten

Jeder testenswerte Lesepfad – [Termine auflisten](https://docs.anivahealth.com/de/api/appointments/list-appointments.md),
[Ergebnisse abrufen](https://docs.anivahealth.com/de/api/appointments/get-results.md),
[Dokument herunterladen](https://docs.anivahealth.com/de/api/documents/download-document.md) – ist leer, bis Tage später eine echte
Blutabnahme stattfindet. Das macht automatisierte Integrationstests umständlich zu schreiben.

Drei `last_name`-Werte sind reserviert, um das zu lösen. Erstelle ein Profil mit einem davon, und
Aniva füllt den unten beschriebenen Zustand vor der Antwort vorab aus, sodass dein nächster Aufruf
ihn bereits sieht:

| `last_name` | Was das Profil erhält |
| - | - |
| `Upcomingtestmann` | Ein bevorstehender `confirmed`-Termin mit einem zugewiesenen Panel. Noch keine Ergebnisse. |
| `Partialtestmann` | Ein vergangener `blood_drawn`-Termin. Etwa die **Hälfte** des Panels ist ausgewertet; [Ergebnisse abrufen](https://docs.anivahealth.com/de/api/appointments/get-results.md) hat den Status `in_progress`. |
| `Fulltestmann` | Ein vergangener `blood_drawn`-Termin. **Jeder** Biomarker im Panel ist ausgewertet, `status: "completed"`, und ein Laborbericht als PDF in `documents[]`. |

Groß- und Kleinschreibung spielen keine Rolle. Jedes andere Feld – einschließlich `date_of_birth`
und `sex` – wird normal gespeichert und verwendet, sodass die zurückgegebenen Referenzbereiche den
echten alters- und geschlechtsspezifischen Bereichen des erstellten Profils entsprechen.

Der Termin wird am Standort **Aniva Test** in einem tatsächlich buchbaren Zeitfenster gebucht, mindestens fünf Tage
in der Zukunft (oder vor fünf Tagen bei vergangenen Zuständen). Beim Seeding wird kein Laborauftrag erteilt und kein
Kurier gebucht.

> [!NOTE]
>
> Gib Testprofilen eine Adresse, die du kontrollierst. Die Terminerinnerungen von Aniva werden über
> `scheduled_at` gesteuert, sodass das Fixture für bevorstehende Termine sie versendet, wenn das Profil nicht über
> `transactional_emails_enabled: false` abgemeldet ist.

Das Panel wird zufällig aus den Panels gewählt, die dein API-Key sehen kann, sodass sich die `panel_id` immer
über dein eigenes [Panels auflisten](https://docs.anivahealth.com/de/api/panels/list-panels.md) auflösen lässt. Klinische Biomarker erhalten einen Wert innerhalb ihres
Referenzbereichs; Gene erhalten einen zufälligen Genotyp aus den Referenzdaten von Aniva, aus dem sich die passenden Varianten, die klinische Signifikanz und die rs-IDs ergeben.

> [!NOTE]
>
> Panel und Werte werden bei jedem Erstellen neu generiert, prüfe daher die Struktur statt eines bestimmten
> Panels oder exakter Zahlen.

## Antwort

Bei Erfolg gibt die API `201 Created` mit dem neu erstellten Profil zurück.

**id** `string` *required*

Eindeutige Profil-ID (UUID).

**handle** `string`

Profil-Handle oder Benutzername. Kann `null` sein.

**first\_name** `string`

Vorname. Kann `null` sein.

**last\_name** `string`

Nachname. Kann `null` sein.

**email** `string`

E-Mail-Adresse. Kann `null` sein.

**phone** `string`

Telefonnummer im E.164-Format. Kann `null` sein.

**sex** `integer`

Biologisches Geschlecht nach ISO/IEC 5218 (`0` = unbekannt, `1` = männlich, `2` = weiblich). Kann `null` sein.

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

Geburtsdatum im Format `YYYY-MM-DD`. Kann `null` sein.

**height** `number`

Körpergröße in Zentimetern. Kann `null` sein.

**weight** `number`

Gewicht in Kilogramm. Kann `null` sein.

**language** `string`

Bevorzugte Sprache, einer der 32 Codes oben.

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

Ob dieses Profil transaktionale (programmatische) E-Mails erhält. `null`, wenn noch nie gesetzt.

**created\_at** `string`

ISO-8601-Zeitstempel der Profilerstellung.

**updated\_at** `string`

ISO-8601-Zeitstempel der letzten Aktualisierung. `null` bei neu erstellten Profilen.

## Fehlerantworten

| Status | Beschreibung |
| - | - |
| `400` | Validierungsfehler – ein oder mehrere Felder haben die Validierung nicht bestanden. |
| `403` | Zugriff verweigert – dein API-Key hat keinen Zugriff auf diese Operation oder die Profilgruppe liegt außerhalb deines Zugriffskontexts. |
| `404` | Profilgruppe nicht gefunden. |
| `409` | Für die angegebene `email` existiert bereits ein Profil (die Antwort enthält die Adresse), oder für dieselbe Person (siehe unten), oder der `Idempotency-Key` wurde mit einem anderen Body wiederverwendet, oder die ursprüngliche Anfrage ist noch nicht abgeschlossen. |
| `500` | Interner Serverfehler. |

Ein `409` sieht so aus – behandle ihn als „Dieses Profil existiert bereits“ und schlage das Profil über
[Profile auflisten](https://docs.anivahealth.com/de/api/profiles/list-profiles.md) (`?email=`) nach, statt das Erstellen erneut zu versuchen:

```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"
}
```

Eine Person mit demselben Vornamen, Nachnamen, Geschlecht und Geburtsdatum wie ein Profil, das dein Key sehen kann,
erhält einen `409` mit `error_name: "duplicate_profile_error"`. Verwende die zurückgegebene `profile_id`, statt
ein zweites Profil zu erstellen:

```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"
}
```

Die Sandbox-Nachnamen, die Testdaten erzeugen, sind davon ausgenommen.

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