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

# Profile auflisten

> Patientenprofile auflisten oder anhand der E-Mail-Adresse suchen

Liste Patientenprofile auf, auf die dein API-Key zugreifen kann, oder schlage ein Profil anhand der exakten E-Mail-Adresse nach.

Wenn `email` angegeben ist, führt der Endpunkt eine über Redis zwischengespeicherte
exakte Suche anhand der kanonischen Anmelde-E-Mail durch und gibt 0 oder 1 Ergebnis zurück;
`limit` und `offset` werden in diesem Fall ignoriert. Wird der Parameter weggelassen, gibt
der Endpunkt eine paginierte Liste von Profilen im Zugriffskontext deines API-Schlüssels zurück.

Der E-Mail-Abgleich erfolgt exakt und ohne Berücksichtigung der Groß- und Kleinschreibung – Teilstring- und Präfix-Treffer werden nicht unterstützt.
Geprüft wird nur die kanonische Anmelde-E-Mail; alternative Adressen wie `work_email` werden nicht
berücksichtigt.

Erfordert den Scope `profiles_view` oder `impersonate`.

## Anfrage

### Query-Parameter

**email** `string`

Nach exakter E-Mail-Adresse filtern (Groß- und Kleinschreibung wird ignoriert). Wenn gesetzt, liefert die Abfrage 0 oder 1 Ergebnis und
`limit`/`offset` werden ignoriert. Die Suche erfolgt über einen Redis-gecachten Reverse-Index mit
indiziertem SQL-Fallback.

**limit** `integer` (default: 100)

Maximale Anzahl zurückgegebener Profile. Standardmäßig 100, maximal 500. Wird ignoriert, wenn `email` gesetzt ist.

**offset** `integer` (default: 0)

Anzahl der Profile, die für die Paginierung übersprungen werden. Standardmäßig 0. Wird ignoriert, wenn `email` gesetzt ist.

## Antwort

Bei Erfolg gibt die API `200 OK` mit einem Array von Profilobjekten zurück. Die Struktur jedes
Eintrags entspricht [Profil abrufen](https://docs.anivahealth.com/de/api/profiles/get-profile.md).

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

**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. Kann `null` sein.

## Hinweise zum Verhalten

* Ein leeres Array wird sowohl zurückgegeben, wenn kein Profil zur E-Mail passt, als auch dann, wenn ein Treffer
  außerhalb deines Zugriffskontexts existiert. Das ist beabsichtigt – so gibt der Endpunkt keine Hinweise auf die
  Existenz von Profilen, die du nicht lesen kannst.
* Neu erstellte Profile sind sofort über `email` auffindbar, da der Erstellungsablauf
  den Cache synchron aufwärmt.
* Die ungefilterte Liste ist absteigend nach `created_at` sortiert (neueste zuerst) und wird über
  `limit` und `offset` paginiert.

## Wiederholte Aufrufe

Aniva speichert die Antwort dieses Endpunkts für jeden API-Key 5 Minuten lang. Ein erneuter Aufruf innerhalb
dieser Zeit erhält die gespeicherte Antwort. Die Header `Cache-Status` und `Age` zeigen, dass die Antwort
gespeichert ist und wie alt sie ist.

Um sofort über eine Änderung informiert zu werden, abonniere die Webhook-Events `profile.created`, `profile.updated` und `profile.deleted`.
Siehe [Wiederholte Lesezugriffe](https://docs.anivahealth.com/de/concepts/webhooks.md#wiederholte-abrufe).

## Fehlerantworten

| Status | Beschreibung |
| - | - |
| `400` | Validierungsfehler – ungültiges E-Mail-Format oder `limit`/`offset` außerhalb des zulässigen Bereichs. |
| `403` | Zugriff verweigert – dein API-Key hat nicht den erforderlichen Scope (`profiles_view`/`impersonate`). |
| `500` | Interner Serverfehler. |

```bash cURL (lookup by email) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/profiles?email=maria.schmidt@example.com' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (paginated list) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/profiles?limit=50&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 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": "2026-04-01T11:05:00Z"
  }
]
```

```json 200 (no match) theme={null}
[]
```

```json 400 theme={null}
{
  "error": "email: Invalid email format"
}
```


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