> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Benutzeroperationen: Benutzer-CRUD für Anbieter

> Didit Anbieter-Benutzer über die Management API anlegen, abrufen, aktualisieren, Status ändern und löschen. Abrechnung pro Nutzung, keine Verträge.



Prompt für Benutzervorgänge
        Prompt in die Zwischenablage kopieren



      
      

\<pre>

\````# Goal — full CRUD over Didit User entities

Core CRUD operations sit under `https://verification.didit.me/v3/users/` authenticated with `x-api-key: $DIDIT_API_KEY`. Profile attachment endpoints use the organization/application path and the User's `didit_internal_id`. Each User is keyed by `vendor_data` (case-sensitive, unique per application).

\## Endpoint catalog

\| Action | Method + path |
\|---|---|
\| List users | `GET /v3/users/` |
\| Get one user | `GET /v3/users/{vendor_data}/` |
\| Create user | `POST /v3/users/create/` |
\| Upload profile face | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` |
\| Update profile | `PATCH /v3/users/{vendor_data}/` |
\| Change status | `PATCH /v3/users/{vendor_data}/update-status/` |
\| Batch delete | `POST /v3/users/delete/` |

\## List (with filters)

\```bash
curl -G https://verification.didit.me/v3/users/ \
-H "x-api-key: $DIDIT_API_KEY" \
\--data-urlencode "status=ACTIVE" \
\--data-urlencode "search=jane" \
\--data-urlencode "page_size=50"
\```

\## Get one user

\```bash
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

\## Create

\```bash
curl -X POST https://verification.didit.me/v3/users/create/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vendor_data": "user-42",
"display_name": "Jane Doe",
"metadata": {"tier": "premium", "signup_source": "web"}
}'
\```

Not idempotent — retrying with the same `vendor_data` returns conflict. `GET` first or PATCH instead.

\## Upload an imported profile face

\```bash
\# First read didit_internal_id from GET /v3/users/{vendor_data}/
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

This attaches a trusted face image to the User profile and enrolls it for duplicate detection and face search. It does not add the face to a blocklist.

\## Update profile

\```bash
curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata": {"tier": "enterprise"}}'
\```

Mutable: `display_name`, `metadata`, `tags`. Read-only (verified): `full_name`, `date_of_birth`, `portrait_image`, all aggregate counters, `features` map.

\## Change status

\```bash
curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "BLOCKED", "reason": "Chargeback fraud pattern"}'
\```

Valid statuses: `ACTIVE`, `FLAGGED`, `BLOCKED`. `BLOCKED` users have new sessions auto-declined.

\## Batch delete

\```bash
curl -X POST https://verification.didit.me/v3/users/delete/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"vendor_data_list": ["user-42", "user-43", "user-44"]}'
\```

Idempotent — already-deleted is a no-op. Returns a count, `{"deleted": <int>}`, not a per-item result. The user records and every biometric template retained for them are removed permanently. Verification sessions are not covered by this endpoint; delete those with the session delete endpoints.

\## Webhooks fired

\| Operation | Event |
\|---|---|
\| create | none for the create call itself — the first `user.data.updated` arrives when a session or a PATCH first fills the profile |
\| update (PATCH) | `user.data.updated` with `changed_fields` |
\| update-status | `user.status.updated` |
\| delete | none — record the deletion on your own side if you need to react to it |

\## Failure modes

\- `401` — missing / invalid `x-api-key`.
\- `403` — the API key is not valid for this application.
\- `409` on create — `vendor_data` already exists; switch to PATCH.
\- `404` — no entity for that `vendor_data` (case-sensitive!).
\- `429` — rate-limited; back off using `Retry-After`.

\## Response shape

See /reference/data-models and /entities/users/data-model for the full User schema.

\## Sources of truth

\- /management-api/users/list, /management-api/users/get, /management-api/users/create — per-endpoint reference
\- /entities/users/data-model — field-by-field schema
\- /entities/webhooks — entity event payloads
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Einfügen in

Die zentrale Verwaltung von Benutzerentitäten erfolgt über öffentliche Endpoints unter `/v3/users/`. Profilanhänge wie der Upload eines importierten Gesichts laufen über den Pfad mit Organisation und Anwendung und verwenden `didit_internal_id`. Diese Seite bietet einen konzeptionellen Überblick. Die vollständigen Schemas für Anfrage und Antwort finden Sie in der [API-Referenz](https://docs.didit.me/de/management-api/users/list.md).## Benutzer auflisten**`GET /v3/users/`**Gibt eine paginierte Liste der Benutzer Ihrer Anwendung zurück. Unterstützt Filter nach Status, Suche, Datumsbereich und mehr.```bash theme={null}
curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"
```Anwendungsfälle:- Eine Teilmenge der Benutzer jeden Tag in Ihr Data Warehouse synchronisieren.
- Markierte Benutzer für eine Analysten-Warteschlange finden.
- Benutzer nach Anzeigename suchen.## Einen Benutzer abrufen**`GET /v3/users/{vendor_data}/`**Ruft einen einzelnen Benutzer anhand von `vendor_data` ab. Gibt das vollständige [Datenmodell](https://docs.didit.me/de/entities/users/data-model.md) einschließlich der aggregierten Zähler zurück.```bash theme={null}
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
```> [!NOTE]
>
> `vendor_data` in der URL unterscheidet zwischen Groß- und Kleinschreibung. Übergeben Sie immer exakt den Wert, den Sie bei der Erstellung der Sitzung verwendet haben.## Benutzer erstellen**`POST /v3/users/create/`**Erstellt eine Benutzerentität, bevor eine Sitzung gestartet wird. Nützlich für:- Metadaten oder benutzerdefinierte Felder anlegen, bevor die Kundin oder der Kunde sich verifiziert.
- Einen Anfangsstatus setzen (z. B. `FLAGGED`, während Ihr Onboarding-Team manuelle Dokumente prüft).
- Benutzer aus einer bestehenden Datenbank vorab laden, damit Sie ab dem ersten Tag eine vollständige Liste haben.```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_source": "web" }
  }'
```Existiert bereits ein Benutzer mit diesem `vendor_data`, gibt der Aufruf einen Konfliktfehler zurück. Verwenden Sie in diesem Fall `PATCH`, um ihn zu aktualisieren.Sie können auch Kontaktdaten senden: `first_name` und `last_name` (werden zu `full_name` zusammengefügt, wenn Sie keinen angeben), `email`, `phone_number` und `country`.
Didit speichert `email` und `phone_number` in `metadata.contact` und `country` in `metadata.address`.Um die Person im selben Aufruf zur Verifizierung einzuladen, fügen Sie `send_verification_link: true` zusammen mit einer `email` und einer `workflow_id` hinzu.
Didit erstellt für die Person eine Verifizierungssitzung mit diesem Workflow und sendet ihr den Link per E-Mail.
Das Feld `verification_link` der Antwort enthält `session_id`, `session_number`, `status`, `url`, `workflow_id` und `email` der Sitzung. Es ist `null`, wenn Sie keinen Link anfordern.
Die Prüfungen und Fehler finden Sie unter [Benutzer erstellen](https://docs.didit.me/de/management-api/users/create.md#verifizierungslink-senden).## Importiertes Gesicht hochladen**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**Hängt ein vertrauenswürdiges Gesichtsbild an ein bestehendes Benutzerprofil an. Das ist der richtige nächste Schritt, wenn Sie Benutzer von einem anderen Anbieter importieren und möchten, dass Didit deren Gesichtsnachweise übernimmt, bevor die erste Didit-Sitzung stattfindet.```bash theme={null}
# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```Die Anfragefelder, Limits, Endpoints zum Auflisten und Löschen sowie den Unterschied zur Sperrliste finden Sie unter [Gesicht des Benutzers hochladen](https://docs.didit.me/de/management-api/users/upload-face.md).## Benutzer aktualisieren**`PATCH /v3/users/{vendor_data}/`**Aktualisiert veränderliche Profilfelder. Die meisten Felder, die aus verifizierten Sitzungen stammen, sind schreibgeschützt. Ein Versuch, sie per PATCH zu ändern, wird ignoriert oder im Audit-Log markiert.**Veränderliche Felder:** `display_name`, `metadata`, `tags`.
**Nach der Verifizierung schreibgeschützt:** `full_name`, `date_of_birth`, `portrait_image`, alle aggregierten Zähler und die `features`-Map.```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'
```Löst den Webhook `user.data.updated` mit dem Array `changed_fields` aus.## Status ändern**`PATCH /v3/users/{vendor_data}/update-status/`**Verschiebt einen Benutzer zwischen `ACTIVE`, `FLAGGED` und `BLOCKED`. Statusänderungen wirken sich auf künftige Sitzungen und Transaktionen aus.```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'
```| Von → nach | Typischer Auslöser |
| - | - |
| `ACTIVE` → `FLAGGED` | Transaktionsregel, Prüfung durch Analysten, laufender AML-Treffer |
| `ACTIVE` → `BLOCKED` | Bestätigter Betrug, manueller Sperrlisteneintrag, Sperrlisten-Treffer |
| `FLAGGED` → `ACTIVE` | Analyst hat die Prüfung freigegeben |
| `BLOCKED` → `ACTIVE` | Manuelle Freigabe durch einen Analysten |Löst den Webhook `user.status.updated` aus.## Benutzer löschen (Batch)**`POST /v3/users/delete/`**Löscht einen oder mehrere Benutzer. Die Benutzerdatensätze werden dauerhaft entfernt, zusammen mit jedem [biometrischen Template](https://docs.didit.me/de/management-api/biometric-templates/overview.md), das nach dem Löschen der Sitzung für sie aufbewahrt wurde. Deren Verifizierungssitzungen sind von diesem Endpoint nicht erfasst. Sie bleiben erhalten, wobei ihre Verknüpfung zum Benutzer entfernt wird. Löschen Sie diese mit [Sitzung löschen](https://docs.didit.me/de/sessions-api/delete-session.md) oder [Sitzungen im Batch löschen](https://docs.didit.me/de/management-api/sessions/batch-delete.md). Transaktionen sind ebenfalls nicht erfasst. Löschen Sie diese in der Console.```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'
```Wählen Sie Benutzer über `vendor_data_list`, über `didit_internal_id_list` oder über beide gleichzeitig aus. Alternativ übergeben Sie `delete_all: true`, um jeden Benutzer der Anwendung zu entfernen. Die Batch-Parameter `filter_*` der Console werden hier mit einem `400` abgelehnt und nicht ignoriert. So kann eine eingeschränkte Absicht nie zu einer vollständigen Löschung werden.Die Antwort enthält eine Anzahl, `{"deleted": <int>}`, kein Ergebnis pro Eintrag. Kennungen ohne Treffer werden stillschweigend übersprungen. Wenn Sie `deleted` mit der Anzahl der gesendeten Kennungen vergleichen möchten, senden Sie daher eine Liste ohne Duplikate.## BerechtigungsmodellAPI-Schlüssel gehören jeweils zu einer Anwendung.
Die primären Geheimschlüssel und die Schlüssel mit Vollzugriff können jeden Endpoint `/v3/users/*` dieser Anwendung aufrufen, einschließlich `delete`.Ein [eingeschränkter API-Schlüssel](https://docs.didit.me/de/console/api-keys.md) benötigt Zugriff auf **Personen** (`users`): Lesezugriff für die `GET`-Endpoints sowie Schreibzugriff zum Erstellen, Aktualisieren, Ändern des Status und Löschen.
Wenn Sie einen Benutzer mit `send_verification_link: true` erstellen, benötigen Sie außerdem Schreibzugriff auf **Sitzungen**, weil dabei eine Sitzung erstellt und deren Link per E-Mail gesendet wird.
Bei einem Schlüssel ohne den erforderlichen Zugriff wird `403` zurückgegeben.
Ein Schlüssel, der auf bestimmte Workflows oder auf genehmigte Sitzungen beschränkt ist, kann die Endpoints `/v3/users/*` überhaupt nicht erreichen.Rollen sind ein Konzept der Console. Die Ressource für Berechtigungen `users` und ihre Claims bestimmen, was ein Teammitglied in der Console tun darf. Bei Anfragen mit API-Schlüsseln werden sie nicht ausgewertet.
Die Matrix dazu finden Sie unter [Rollen und Berechtigungen](https://docs.didit.me/de/console/roles-permissions.md).Damit ein Dienst keine Benutzer löschen kann, geben Sie ihm einen Schlüssel mit reinem Lesezugriff auf **Personen** oder ohne Zugriff auf **Personen**.## Rate-Limits und Idempotenz- Alle Endpoints `/v3/users/*` unterliegen den üblichen [Rate-Limits](https://docs.didit.me/de/integration/rate-limiting.md).
- `create` ist **nicht** idempotent. Ein Wiederholungsversuch mit demselben `vendor_data` gibt einen Konflikt zurück. Vermeiden Sie Duplikate auf Ihrer Seite, oder rufen Sie immer zuerst `GET` auf.
- `delete` ist idempotent. Das Löschen eines bereits gelöschten Benutzers hat keine Wirkung.## Webhooks, die durch diese Vorgänge ausgelöst werden| Vorgang | Webhook |
| - | - |
| `create` | Keiner für den Create-Aufruf selbst: Das erste `user.data.updated` wird ausgelöst, wenn eine Sitzung oder ein Update das Profil erstmals befüllt |
| `update` | `user.data.updated` (mit `changed_fields`) |
| `update-status` | `user.status.updated` |
| `delete` | Keiner: Wenn Sie auf die Löschung reagieren müssen, halten Sie sie auf Ihrer Seite fest |## Nächste Schritte> [card] [Datenmodell](https://docs.didit.me/de/entities/users/data-model.md)
>
> Vollständige Feldreferenz.> [card] [List-API](https://docs.didit.me/de/management-api/users/list.md)
>
> Schema für GET /v3/users/.> [card] [Create-API](https://docs.didit.me/de/management-api/users/create.md)
>
> Schema für POST /v3/users/create/.> [card] [Gesicht hochladen](https://docs.didit.me/de/management-api/users/upload-face.md)
>
> Importierte Gesichtsbilder an Benutzerprofile anhängen.


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