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

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

> Der vendor_data-Identifier verbindet Ihr System mit Didit und bündelt Sitzungen, Transaktionen und Benutzer-/Unternehmensentitäten zu einem Profil.

Prompt zur Verknüpfung von Vendor-Daten
Prompt in die Zwischenablage kopieren

<pre>
  \`\`\`\`# Goal — link every session, transaction, and entity together using `vendor_data`

  `vendor_data` is the string identifier you choose and pass on every API call to bind it to a persistent [User](https://docs.didit.me/entities/users/overview.md) or [Business](https://docs.didit.me/entities/businesses/overview.md) entity. Get this right once and you never have to re-key history afterwards.

  ## Rules

  * `vendor_data` is **opaque** to Didit. Use your stable internal customer id.
  * Choose one canonical id per entity and never change it. Changing it orphans history under a new entity.
  * Prefix by entity type when convenient (`user_...`, `biz_...`) to avoid collisions in your own code.
  * Keep it under 128 chars, case-sensitive stable. Hard limit is 2000 bytes (UTF-8 encoded) - anything over that is rejected with a 400 rather than accepted.
  * **Never put raw PII in it** — it surfaces in webhooks, logs, and API responses.
  * Uniqueness is per application × entity type. User `user-42` and Business `user-42` are different entities (but don't do this).

  ## Where it goes

  | API | Field |
  | - | - |
  | `POST /v3/session/` | top-level `vendor_data` (KYC and KYB) |
  | `POST /v3/transactions/` | top-level `vendor_data` and `applicant.vendor_data` / `counterparty.vendor_data` |
  | `POST /v3/users/create/` / `POST /v3/businesses/create/` | `vendor_data` |
  | `GET /v3/sessions?vendor_data=...` | query param to retrieve history |
  | `GET /v3/users/{vendor_data}/` / `GET /v3/businesses/{vendor_data}/` | path param |

  ## Pattern — pre-create the entity, then run a session

  ```bash
  # 1) Seed the entity with metadata before any session
  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_date": "2026-04-01"}
  }'

  # 2) Run a KYC session linked to the same entity
  curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "workflow_id": "$WORKFLOW_ID",
  "vendor_data": "user-42",
  "callback": "https://myapp.com/return"
  }'

  # 3) Later, retrieve every session for the entity
  curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  --data-urlencode "vendor_data=user-42"
  ```

  ## Auto-create semantics

  If you create a session with a new `vendor_data` and no entity exists, Didit creates the entity automatically with `status: ACTIVE` and links the session.

  ## Failure modes

  * Missing `vendor_data` on session create → session is orphaned, won't appear in any entity profile, cannot be filtered by `vendor_data` later (only by `session_id`).
  * Different case (`User-42` vs `user-42`) → two separate entities. Pick a casing convention and stick to it.
  * Same `vendor_data` across staging and prod apps → no collision; `vendor_data` is scoped per application.

  ## Sources of truth

  * /entities/users/operations — full User CRUD
  * /entities/businesses/operations — full Business CRUD
  * /sessions-api/create-session — session body shape
  * /integration/integration-prompt — canonical end-to-end prompt\`\`\`\`
</pre>

Einfügen in

`vendor_data` ist die Kennung, die Sie bei jeder Sitzung und jeder Transaktion angeben, um sie mit einer [Benutzer](https://docs.didit.me/de/entities/users/overview.md)- oder [Unternehmens](https://docs.didit.me/de/entities/businesses/overview.md)-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` |

> [!WARNING]
>
> 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

```mermaid theme={null}
flowchart TD
    subgraph YourSystem["Your system"]
      Customer["Customer record: user-42"]
    end
    subgraph Didit["Didit platform"]
      Entity["User entity (vendor_data = user-42)"]
      S1[Session #1]
      S2[Session #2]
      T1[Transaction #1]
      T2[Transaction #2]
      F[Face biometric]
    end
    Customer -.vendor_data.-> Entity
    S1 --> Entity
    S2 --> Entity
    T1 --> Entity
    T2 --> Entity
    F --> Entity
```

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

1. Didit sucht in Ihrer Anwendung nach der Entität mit diesem `vendor_data`.
2. Falls sie existiert, wird das neue Objekt mit dieser Entität verknüpft.
3. 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

```bash theme={null}
# 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

> [card] [Übersicht Benutzer](https://docs.didit.me/de/entities/users/overview.md)
>
> Detaillierte Informationen zu Benutzer-Entitäten und -Operationen.

> [card] [Übersicht Unternehmen](https://docs.didit.me/de/entities/businesses/overview.md)
>
> Detaillierte Informationen zu Unternehmens-Entitäten und -Operationen.

> [card] [Sitzung erstellen](https://docs.didit.me/de/sessions-api/create-session.md)
>
> Starten Sie eine Verifizierung für einen vendor\_data-Wert.

> [card] [Transaktion erstellen](https://docs.didit.me/de/management-api/transactions/create.md)
>
> Reichen Sie eine Transaktion ein, die mit einer Entität verknüpft ist.


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