> ## 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.
# Benutzerstatus aktualisieren API: sperren oder markieren
> Didit-Benutzer sperren, markieren oder aktivieren. Der Status gilt für künftige KYC-Sitzungen und Transaktionsprüfungen. Abrechnung pro Aufruf.
Prompt zum Aktualisieren des Benutzerstatus
Prompt in die Zwischenablage kopieren
\
\`Goal: Flip ONLY the lifecycle status of a Didit User entity. Use the full PATCH /v3/users/{vendor_data}/ when you also need to touch other fields.
Endpoint: PATCH https://verification.didit.me/v3/users/{vendor_data}/update-status/
Auth header: x-api-key:
Content-Type: application/json
Path param:
\- vendor_data (string, REQUIRED) — free-form string, NOT a UUID. URL-encode.
Request body:
\- status (enum, REQUIRED) — "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorUserStatusChoices, NOT the session enum).
\- reason (string, optional, max 1000): why the status changed. Recorded as the comment of the STATUS_CHANGED entry in the user's activity (comments[].comment), only when the status actually changes. Webhooks do not carry it.
Status semantics:
\- ACTIVE → normal. New sessions allowed for this vendor_data.
\- FLAGGED → still accepted, highlighted in Console for manual review; filterable with ?status=FLAGGED.
\- BLOCKED → terminal. Adds vendor_data to the system blocklist. Subsequent session creations for the same identifier are rejected with a blocklist hit. Flipping back to ACTIVE/FLAGGED removes the blocklist entry automatically.
curl:
curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/update-status/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"status": "BLOCKED", "reason": "Chargeback fraud pattern confirmed"}'
Response 200: full updated UserDetailItem (same shape as GET /v3/users/{vendor_data}/). See /reference/data-models.
Side effects:
\- Toggles the system blocklist entry when entering/leaving BLOCKED.
\- Writes one STATUS_CHANGED entry to the user's comments activity log (actor = API key identity), with reason as its comment.
\- Idempotent — re-sending the same status is a no-op (no extra audit row, no extra blocklist toggle).
Failure modes:
\- 400 — validation:
\{ "status": "This field is required." }
\{ "status": "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" }
\{ "reason": ["Ensure this field has no more than 1000 characters."] }
\- 401 — missing/invalid x-api-key. { "detail": "Authentication credentials were not provided." }
\- 403 — the API key is revoked or is not valid for this application. { "detail": "You do not have permission to perform this action." }
\- 403: a scoped API key without users write. { "detail": "This API key has no write access to people." }
\- 404 — vendor_data not found (or deleted). { "detail": "Not found." }
\- 429 — rate-limited.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
Einfügen in
## ÜberblickWechselt eine [Benutzer-Entität](https://docs.didit.me/de/entities/users/overview.md) zwischen `ACTIVE`, `FLAGGED` und `BLOCKED`. Den vollständigen Zustandsautomaten finden Sie im [Lebenszyklus der Entität](https://docs.didit.me/de/entities/lifecycle.md).## Wann Sie den Endpoint verwenden sollten- **Einen Benutzer sperren**, nachdem Betrug oder ein Compliance-Verstoß bestätigt wurde.
- **Einen Benutzer markieren**, bis eine manuelle Prüfung abgeschlossen ist, ohne ihn vollständig zu sperren.
- **Blockierung aufheben**: Heben Sie die Blockierung eines Benutzers nach erfolgreicher Behebung auf.
- **Externe Signale weitergeben**: Wenn Ihre eigene Betrugserkennung einen Benutzer mit einem Wert über dem Schwellenwert bewertet, setzen Sie ihn über diesen Endpoint auf `FLAGGED`.## Hinweise- Gültige Werte: `ACTIVE`, `FLAGGED`, `BLOCKED`. Ungültige Werte geben 400 zurück.
- Übergeben Sie optional einen `reason` (bis zu 1000 Zeichen), um festzuhalten, warum sich der Status geändert hat.
Didit speichert ihn als Kommentar des Eintrags zur Statusänderung in der Aktivität der Person: `comments[].comment` beim Benutzer und **Aktivität** in der Business Console.
Er wird nur gespeichert, wenn sich der Status tatsächlich ändert.
- Bei Benutzern mit dem Status `BLOCKED` werden alle neuen Sitzungen und alle neuen Transaktionen automatisch abgelehnt.
- Es wird ein Webhook-Ereignis `user.status.updated` ausgelöst, das `previous_status` und `status` enthält.
Der Webhook enthält kein `reason`.## Durchsetzung| Status | Auswirkung auf neue Sitzungen | Auswirkung auf neue Transaktionen |
| - | - | - |
| `ACTIVE` | Normaler Ablauf | Normaler Ablauf |
| `FLAGGED` | Erlaubt, wird aber an `IN_REVIEW` weitergeleitet | Erlaubt; kann je nach Regeln automatisch eskaliert werden |
| `BLOCKED` | Automatisch abgelehnt | Automatisch abgelehnt |## BerechtigungenDas primäre Secret und [API-Schlüssel](https://docs.didit.me/de/console/api-keys.md) mit vollem Zugriff können diesen Endpoint immer aufrufen.
Ein API-Schlüssel mit benutzerdefiniertem Zugriff benötigt Schreibzugriff auf **Personen** (`users`).
Ein Schlüssel, der auf bestimmte Workflows oder auf genehmigte Sitzungen beschränkt ist, kann diesen Endpoint nicht erreichen.Die [Rollen und Berechtigungen](https://docs.didit.me/de/console/roles-permissions.md) der Console bestimmen, was ein Teammitglied in der Console tun darf. Bei Anfragen mit API-Schlüsseln werden sie nicht ausgewertet.## Verwandte Themen- [Lebenszyklus der Entität](https://docs.didit.me/de/entities/lifecycle.md)
- [Sperrliste für Benutzer](https://docs.didit.me/de/entities/users/blocklist.md)
- [Webhooks für Entitäten](https://docs.didit.me/de/entities/webhooks.md)
## OpenAPI
````yaml de/openapi-25.json PATCH /v3/users/{vendor_data}/update-status/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/users/{vendor_data}/update-status/:
patch:
tags:
- Users
summary: Benutzerstatus aktualisieren
description: >-
Nur den Lebenszyklus-`status` eines Benutzers umschalten: `ACTIVE`,
`FLAGGED` oder `BLOCKED` (keine Sitzungsstatus). `BLOCKED` fügt die
`vendor_data` zur System-Sperrliste hinzu; ein Wechsel weg von `BLOCKED`
entfernt diesen Eintrag wieder. Jede Änderung wird als
`STATUS_CHANGED`-Aktivität beim Benutzer mit dem optionalen `reason` als
deren `comment` erfasst. Das Senden des aktuellen Status ändert nichts
und erfasst keinen `reason`. Der Webhook `user.status.updated` überträgt
keinen `reason`.
operationId: update_user_status
parameters:
- name: vendor_data
in: path
required: true
schema:
type: string
description: Ihre eindeutige Kennung für den Benutzer.
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EntityStatusUpdateRequest'
- type: object
properties:
reason:
type: string
nullable: true
maxLength: 1000
description: >-
Warum sich der Status geändert hat. Wird im
Statusänderungseintrag der Benutzeraktivität
(`comments[].comment` und **Activity** in der Business
Console) erfasst, nur wenn sich der Status tatsächlich
ändert. Webhooks übertragen dies nicht.
examples:
Activate:
summary: Benutzer reaktivieren
value:
status: ACTIVE
Flag:
summary: Den Benutzer zur Prüfung markieren
value:
status: FLAGGED
Block:
summary: Benutzer sperren (fügt ihn zur Systemsperrliste hinzu)
value:
status: BLOCKED
Block with reason:
summary: Benutzer sperren und Grund erfassen
value:
status: BLOCKED
reason: Chargeback fraud pattern confirmed
responses:
'200':
description: >-
Benutzerstatus aktualisiert. Vollständiger Benutzerdatensatz
zurückgegeben.
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetailItem'
examples:
Blocked:
value:
didit_internal_id: f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418
vendor_data: user-abc-123
display_name: null
full_name: John Michael Doe
date_of_birth: '1990-05-15'
effective_name: John Michael Doe
status: BLOCKED
metadata:
tier: premium
source: website
portrait_image_url: https:///...
session_count: 3
approved_count: 2
declined_count: 0
in_review_count: 1
issuing_states:
- USA
approved_emails:
- john@example.com
approved_phones:
- '+14155551234'
features:
ID_VERIFICATION: Approved
LIVENESS: Approved
FACE_MATCH: Approved
AML: Approved
features_list:
- feature: ID_VERIFICATION
status: Approved
- feature: LIVENESS
status: Approved
- feature: FACE_MATCH
status: Approved
- feature: AML
status: Approved
last_session_at: '2025-06-15T10:30:00Z'
last_activity_at: '2025-06-15T10:30:00Z'
first_session_at: '2025-06-01T08:00:00Z'
tags:
- uuid: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
tag:
uuid: e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b
name: VIP
color: '#2567FF'
description: null
source: custom
created_at: '2025-05-01T09:00:00Z'
updated_at: '2025-05-01T09:00:00Z'
added_by_email: analyst@acme.com
added_by_name: Jane Analyst
created_at: '2025-06-02T11:00:00Z'
comments:
- uuid: c1111111-2222-4333-8444-555555555555
comment_type: STATUS_CHANGED
comment: Chargeback fraud pattern confirmed
actor_email: null
actor_name: null
previous_status: ACTIVE
new_status: BLOCKED
previous_value: null
new_value: null
changed_fields: []
metadata: null
mentioned_emails: []
created_at: '2025-06-15T10:30:00Z'
created_at: '2025-06-01T08:00:00Z'
updated_at: '2025-06-15T10:30:00Z'
'400':
description: >-
Fehlender oder ungültiger `status` oder ein `reason` mit mehr als
1000 Zeichen.
content:
application/json:
examples:
Missing status:
value:
status:
- This field is required.
Bad status:
value:
status:
- >-
Invalid status. Valid options are: ACTIVE, FLAGGED,
BLOCKED
Reason too long:
value:
reason:
- Ensure this field has no more than 1000 characters.
'401':
description: >-
Keine Anmeldedaten angegeben. Anfragen an `/v3/users/*`-Pfade ohne
einen `x-api-key`-Header (oder `Authorization: Bearer`-Token) werden
von der Authentifizierungs-Middleware abgelehnt, bevor sie die API
erreichen.
content:
application/json:
examples:
Missing credentials:
value:
detail: >-
You must be authenticated with a valid access token to
access this endpoint.
'403':
description: >-
Der Schlüssel kann keine Benutzer für diese Anwendung aktualisieren.
Ein fehlender Schlüssel gibt `403` zurück; ein falscher,
widerrufener oder abgelaufener Schlüssel gibt `401` zurück.
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'404':
description: >-
Für diese Anwendung existiert kein (nicht gelöschter) Benutzer mit
den angegebenen `vendor_data`.
content:
application/json:
examples:
Not found:
value:
detail: Not found.
'429':
description: >-
Rate-Limit überschritten; drosseln Sie die Anfragen und wiederholen
Sie den Versuch nach dem in `Retry-After` angegebenen Intervall.
content:
application/json:
examples:
Rate limited:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X PATCH
'https://verification.didit.me/v3/users/user-abc-123/update-status/'
\
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"status": "BLOCKED"}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.users.update_status(
"user-123",
status="ACTIVE",
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.users.updateStatus("user-123", {
status: "ACTIVE",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.UpdateStatus(ctx, \"user-123\", didit.UsersUpdateStatusParams{\n\tStatus: \"ACTIVE\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.EntityStatusUpdateRequest;
import me.didit.types.UsersUpdateStatusParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.users().updateStatus("user-123",
UsersUpdateStatusParams.builder()
.status(EntityStatusUpdateRequest.Status.of("ACTIVE"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
users->updateStatus('user-123', [
'status' => 'ACTIVE',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.users.update_status(
"user-123",
status: "ACTIVE"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Users.UpdateStatusAsync("user-123", new
UsersUpdateStatusParams
{
Status = "ACTIVE",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
EntityStatusUpdateRequest:
type: object
required:
- status
properties:
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
description: >-
Neuer Lebenszyklusstatus. `BLOCKED` fügt die `vendor_data` außerdem
zur System-Sperrliste hinzu.
UserDetailItem:
type: object
description: >-
Vollständige Benutzerdetails. Erweitert UserListItem um Metadaten,
Kommentare und updated_at.
allOf:
- $ref: '#/components/schemas/UserListItem'
- type: object
properties:
metadata:
type: object
description: >-
Benutzerdefiniertes Metadaten-JSON, das Sie diesem Benutzer
angehängt haben. Standardmäßig `{}`.
tags:
type: array
description: >-
Tag-Zuweisungen. HINWEIS: Bei Detailantworten ist jeder Eintrag
ein Tag-*Link*-Objekt (`{uuid, tag: {...}, added_by_email,
added_by_name, created_at}`), anders als die flache Struktur
`{uuid, name, color}`, die bei Listenantworten verwendet wird.
items:
type: object
properties:
uuid:
type: string
format: uuid
description: UUID der Tag-Zuweisung (nicht des Tags selbst).
tag:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description:
type: string
nullable: true
source:
type: string
enum:
- didit
- custom
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
added_by_email:
type: string
nullable: true
added_by_name:
type: string
nullable: true
created_at:
type: string
format: date-time
comments:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
comment_type:
type: string
enum:
- COMMENT
- STATUS_CHANGED
- METADATA_UPDATED
- TAG_ADDED
- TAG_REMOVED
- PROFILE_UPDATED
comment:
type: string
nullable: true
actor_email:
type: string
nullable: true
actor_name:
type: string
nullable: true
previous_status:
type: string
nullable: true
enum:
- ACTIVE
- FLAGGED
- BLOCKED
- null
new_status:
type: string
nullable: true
enum:
- ACTIVE
- FLAGGED
- BLOCKED
- null
previous_value:
type: object
nullable: true
description: Vorherige Feldwerte für PROFILE_UPDATED-Einträge.
new_value:
type: object
nullable: true
description: Neue Feldwerte für PROFILE_UPDATED-Einträge.
changed_fields:
type: array
items:
type: string
description: >-
Namen der Felder, die durch einen PROFILE_UPDATED-Eintrag
geändert wurden.
metadata:
type: object
nullable: true
mentioned_emails:
type: array
items:
type: string
created_at:
type: string
format: date-time
description: >-
Aktivitätsprotokoll und Kommentare für diesen Benutzer
(Statusänderungen, Profilbearbeitungen, manuelle Notizen).
updated_at:
type: string
format: date-time
UserListItem:
type: object
description: Ein verifizierter Benutzer.
properties:
didit_internal_id:
type: string
format: uuid
description: Didits stabile interne UUID für diesen Benutzer.
vendor_data:
type: string
nullable: true
description: >-
Ihre eindeutige Kennung für diesen Benutzer (beim Erstellen von
Sitzungen übergeben). Dies kann null sein, wenn keine Vendor-Kennung
angegeben wurde.
display_name:
type: string
nullable: true
description: Von Ihnen festgelegter benutzerdefinierter Anzeigename
full_name:
type: string
nullable: true
description: Aus verifizierten Dokumenten extrahierter vollständiger Name
date_of_birth:
type: string
format: date
nullable: true
effective_name:
type: string
nullable: true
description: >-
Bester verfügbarer Name: display_name, falls gesetzt, andernfalls
full_name
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
description: >-
Lebenszyklusstatus des Benutzerdatensatzes (KEIN Sitzungsstatus).
`ACTIVE` ist der Standard, `FLAGGED` markiert den Benutzer für
manuelle Prüfung, `BLOCKED` verhindert neue Sitzungen für dieses
`vendor_data`.
portrait_image_url:
type: string
nullable: true
description: >-
Vorsignierte URL des Porträtfotos des Benutzers (läuft nach wenigen
Stunden ab)
session_count:
type: integer
description: Gesamtzahl der Verifizierungssitzungen für diesen Benutzer
approved_count:
type: integer
description: Anzahl der genehmigten Sitzungen
declined_count:
type: integer
description: Anzahl der abgelehnten Sitzungen
in_review_count:
type: integer
description: Anzahl der Sitzungen in Prüfung
issuing_states:
type: array
items:
type: string
description: >-
ISO 3166-1-Alpha-3-Codes der Ausstellungsländer, die auf den
genehmigten Ausweisdokumenten dieses Benutzers gefunden wurden, z.
B. `["USA", "ESP"]`. Leeres Array, wenn keine vorhanden sind.
approved_emails:
type: array
items:
type: string
description: >-
Verifizierte E-Mail-Adressen, die aus den genehmigten Sitzungen
dieses Benutzers erfasst wurden, z. B. `["john@example.com"]`.
approved_phones:
type: array
items:
type: string
description: >-
Verifizierte Telefonnummern, die aus den genehmigten Sitzungen
dieses Benutzers erfasst wurden, z. B. `["+14155551234"]`.
features:
type: object
description: >-
Aggregierter Status pro Funktion über alle Sitzungen dieses
Benutzers hinweg. Mögliche Schlüssel: `ID_VERIFICATION`, `NFC`,
`LIVENESS`, `FACE_MATCH`, `POA`, `QUESTIONNAIRE`,
`EMAIL_VERIFICATION`, `PHONE`, `AML`, `IP_ANALYSIS`,
`AGE_ESTIMATION`, `DATABASE_VALIDATION`. Mögliche Werte: `Approved`,
`Declined`, `In Review`, `Not Finished`, `Resub Requested`.
features_list:
type: array
items:
type: object
properties:
feature:
type: string
status:
type: string
description: >-
Dieselben Daten wie `features`, als geordnetes Array von `{feature,
status}`-Objekten.
last_session_at:
type: string
format: date-time
nullable: true
description: Zeitstempel der letzten Sitzung
first_session_at:
type: string
format: date-time
nullable: true
description: Zeitstempel der ersten Sitzung
last_activity_at:
type: string
format: date-time
nullable: true
description: >-
Zeitstempel der letzten Aktivität bei diesem Benutzer (Sitzung,
Transaktion, Statusänderung, Datenbearbeitung usw.).
tags:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description: Diesem Benutzer zugewiesene Tags
created_at:
type: string
format: date-time
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in
der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter
Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese-
oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte
Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und
auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen
oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde,
der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder
die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei
einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows
oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff
erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne
Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als
null. Siehe https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.