Benutzeroperationen: Benutzer-CRUD für Anbieter

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.

Benutzer auflisten

GET /v3/users/ Gibt eine paginierte Liste der Benutzer Ihrer Anwendung zurück. Unterstützt Filter nach Status, Suche, Datumsbereich und mehr.

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 einschließlich der aggregierten Zähler zurück.

curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"

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.

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.

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.

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

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.

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.

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, 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 oder Sitzungen im Batch löschen. Transaktionen sind ebenfalls nicht erfasst. Löschen Sie diese in der Console.

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.

Berechtigungsmodell

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

Datenmodell

Vollständige Feldreferenz.

List-API

Schema für GET /v3/users/.

Create-API

Schema für POST /v3/users/create/.

Gesicht hochladen

Importierte Gesichtsbilder an Benutzerprofile anhängen.

Übersicht

Preise

Workflows & Verifizierung

Prüfung & Betrieb

Entitäten (Benutzer & Unternehmen)

Einstellungen & Anpassung

Sicherheit & Compliance

Didit Academy

Ressourcen

Benutzeroperationen: Benutzer-CRUD für Anbieter

Benutzer auflisten

Einen Benutzer abrufen

Benutzer erstellen

Importiertes Gesicht hochladen

Benutzer aktualisieren

Status ändern

Benutzer löschen (Batch)

Berechtigungsmodell

Rate-Limits und Idempotenz

Webhooks, die durch diese Vorgänge ausgelöst werden

Nächste Schritte

Datenmodell

List-API

Create-API

Gesicht hochladen

​Benutzer auflisten

​Einen Benutzer abrufen

​Benutzer erstellen

​Importiertes Gesicht hochladen

​Benutzer aktualisieren

​Status ändern

​Benutzer löschen (Batch)

​Berechtigungsmodell

​Rate-Limits und Idempotenz

​Webhooks, die durch diese Vorgänge ausgelöst werden

​Nächste Schritte

Datenmodell

List-API

Create-API

Gesicht hochladen

Benutzer auflisten

Einen Benutzer abrufen

Benutzer erstellen

Importiertes Gesicht hochladen

Benutzer aktualisieren

Status ändern

Benutzer löschen (Batch)

Berechtigungsmodell

Rate-Limits und Idempotenz

Webhooks, die durch diese Vorgänge ausgelöst werden

Nächste Schritte