vendor_data-Verknüpfung: IDs an Entitäten binden

vendor_data ist die Kennung, die Sie bei jeder Sitzung und jeder Transaktion angeben, um sie mit einer Benutzer- oder Unternehmens-Entität zu verknüpfen. Es ist das wichtigste Feld für die Entitätsaggregation. Wenn Sie es richtig setzen, funktionieren alle nachgelagerten Funktionen (Profilverlauf, Transaktionsüberwachung, Durchsetzung von Sperrlisten, laufende AML-Überwachung) reibungslos.

Was es ist

vendor_data ist eine Zeichenkette, die Sie selbst wählen. Didit behandelt sie als undurchsichtige Kennung und interpretiert ihren Inhalt nicht. Typische Werte:

Ihr System	Geeignete `vendor_data`-Werte
Interne Benutzerdatenbank	`user_1234`, `uuid-v4` des Benutzers
Kundenseitige ID	`CUST-2026-00042`, gehashte E-Mail-Adresse
Multi-Tenant-SaaS	`tenant_acme:user_1234`
B2B-Plattform	`company-hq-global`, `tax-id-US-123456789`

Fügen Sie keine personenbezogenen Daten (PII) wie E-Mail-Adressen, Telefonnummern oder unveränderte Steuernummern direkt in vendor_data ein. Hashen oder präfixieren Sie diese Werte. vendor_data erscheint in Webhook-Payloads und wird so lange gespeichert, wie die Entität existiert.

Wie Verknüpfungen entstehen

Wenn Sie eine Sitzung oder Transaktion mit einem vendor_data-Wert einreichen:

Didit sucht in Ihrer Anwendung nach der Entität mit diesem vendor_data.
Falls sie existiert, wird das neue Objekt mit dieser Entität verknüpft.
Falls nicht, legt Didit die Entität an (mit status: ACTIVE) und verknüpft das neue Objekt.

Das gilt für:

POST /v3/session/: KYC- und Unternehmensverifizierungs-Sitzungen (KYB)
POST /v3/transactions/: Transaktionen (sowohl für den Antragsteller als auch für die Gegenpartei)
Die Felder applicant.vendor_data / counterparty.vendor_data innerhalb von Transaktions-Payloads

Eindeutigkeit und Geltungsbereich

vendor_data ist pro Anwendung eindeutig, nicht global über Didit hinweg:

Geltungsbereich	Eindeutigkeitsgarantie
Innerhalb einer Anwendung	`vendor_data` ist pro Entitätstyp eindeutig (Benutzer und Unternehmen sind getrennte Namensräume)
Über Anwendungen in Ihrer Organisation hinweg	`vendor_data` wird nicht geteilt: Derselbe Wert in zwei Anwendungen bezeichnet zwei verschiedene Entitäten
Über Organisationen hinweg	Nicht geteilt: Jede Organisation hat eigene Entitätstabellen

Dadurch können Sie denselben vendor_data-Wert in einer Staging- und einer Produktionsanwendung verwenden, ohne dass es zu Kollisionen kommt. Außerdem können Sie einen Benutzer user-42 und ein Unternehmen user-42 haben, ohne dass es zu Kollisionen kommt. Aus Gründen der Übersichtlichkeit wird das allerdings nicht empfohlen.

Was passiert, wenn Sie `vendor_data` weglassen

Sie können eine Sitzung ohne vendor_data erstellen. In diesem Fall:

Für die Sitzung wird keine Entität angelegt.
Die Sitzung ist verwaist: Sie erscheint in keinem Benutzer- oder Unternehmensprofil.
Sie können die Sitzung später nicht über vendor_data abrufen, sondern nur über session_id.

Verwenden Sie dieses Muster nur für anonyme oder einmalige Verifizierungen, bei denen keine Entitätsaggregation nötig ist. Für jede Integration, die erneute Verifizierungen, Transaktionen oder laufende Überwachung umfasst, geben Sie immer vendor_data an.

Beispiel: Entität vorab anlegen und dann Sitzungen durchführen

# 1. Pre-create the User with initial metadata
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_date": "2026-04-01" }
  }'

# 2. Create a User Verification (KYC) session for the same user
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_kyc_standard",
    "vendor_data": "user-42"
  }'

# 3. Later, submit a transaction tied to the same user
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "tx-0001",
    "direction": "OUTBOUND",
    "amount": "500.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "user-42" },
    "counterparty": { "name": "Acme Corp" }
  }'

Alle drei Aufrufe sind mit derselben Benutzerentität verknüpft. Wenn Sie später GET /v3/users/user-42/ aufrufen, sehen Sie die Anzahl der Sitzungen, die Zähler für genehmigte und abgelehnte Sitzungen, die verknüpften Transaktionen und die neuesten Profildaten.

Externe IDs migrieren

Wenn Sie Didit nach der Nutzung eines bestehenden KYC-Anbieters einführen, übergeben Sie Ihre bestehenden, stabilen Benutzer-IDs von Anfang an als vendor_data. So lässt sich Folgendes leicht umsetzen:

Abgleich der Didit-Daten mit Ihrer internen Datenbank.
Massenimport historischer Benutzer über den CSV-Import in der Konsole, bevor Sie Sitzungen durchführen.
Erhalt von Beziehungen, wenn Sie später für die Transaktionsüberwachung zu Didit migrieren.

Regeln, Konventionen und Best Practices

Regel	Warum
Wählen Sie pro Entität einen kanonischen Bezeichner und ändern Sie ihn nie	Änderungen erzeugen eine neue Entität und lassen den Verlauf verwaisen
Präfixieren Sie `vendor_data`-Werte nach Entitätstyp (`user_...`, `biz_...`)	Verhindert versehentliche Kollisionen zwischen Namensräumen in Ihrem eigenen Code
Halten Sie `vendor_data` stabil und beachten Sie die Groß-/Kleinschreibung	Didit normalisiert die Groß-/Kleinschreibung nicht
Halten Sie `vendor_data` unter 128 Zeichen	Passt problemlos in Datenbankindizes
Geben Sie niemals rohe PII preis	`vendor_data` erscheint in Webhooks, Audit-Logs und API-Antworten

Nächste Schritte

Übersicht Benutzer

Detaillierte Informationen zu Benutzer-Entitäten und -Operationen.

Übersicht Unternehmen

Detaillierte Informationen zu Unternehmens-Entitäten und -Operationen.

Sitzung erstellen

Starten Sie eine Verifizierung für einen vendor_data-Wert.

Transaktion erstellen

Reichen Sie eine Transaktion ein, die mit einer Entität verknüpft ist.

Übersicht

Preise

Workflows & Verifizierung

Prüfung & Betrieb

Entitäten (Benutzer & Unternehmen)

Einstellungen & Anpassung

Sicherheit & Compliance

Didit Academy

Ressourcen

vendor_data-Verknüpfung: IDs an Entitäten binden

Was es ist

Wie Verknüpfungen entstehen

Eindeutigkeit und Geltungsbereich

Was passiert, wenn Sie `vendor_data` weglassen

Beispiel: Entität vorab anlegen und dann Sitzungen durchführen

Externe IDs migrieren

Regeln, Konventionen und Best Practices

Nächste Schritte

Übersicht Benutzer

Übersicht Unternehmen

Sitzung erstellen

Transaktion erstellen

​Was es ist

​Wie Verknüpfungen entstehen

​Eindeutigkeit und Geltungsbereich

​Was passiert, wenn Sie vendor_data weglassen

​Beispiel: Entität vorab anlegen und dann Sitzungen durchführen

​Externe IDs migrieren

​Regeln, Konventionen und Best Practices

​Nächste Schritte

Übersicht Benutzer

Übersicht Unternehmen

Sitzung erstellen

Transaktion erstellen

Was es ist

Wie Verknüpfungen entstehen

Eindeutigkeit und Geltungsbereich

Was passiert, wenn Sie `vendor_data` weglassen

Beispiel: Entität vorab anlegen und dann Sitzungen durchführen

Externe IDs migrieren

Regeln, Konventionen und Best Practices

Nächste Schritte