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

# Collegamento vendor_data: unire ID ed entità

> vendor_data collega il tuo sistema a Didit: lega sessioni, transazioni e entità Utente/Azienda in un unico profilo. A consumo per chiamata.

Prompt per il collegamento dei dati del fornitore
Copia il prompt negli appunti

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

Incolla in

`vendor_data` è l'identificatore che fornisci in ogni sessione e transazione per collegare la sessione o la transazione a un'entità [Utente](https://docs.didit.me/it/entities/users/overview.md) o [Azienda](https://docs.didit.me/it/entities/businesses/overview.md). È il campo più importante per l'aggregazione delle entità: se lo imposti correttamente, ogni funzionalità a valle (cronologia del profilo, monitoraggio delle transazioni, applicazione delle blocklist e monitoraggio AML continuo) funziona senza intoppi.

## Cos'è

`vendor_data` è una **stringa** che scegli tu. Didit la tratta come un identificatore opaco e non ne interpreta il contenuto. Valori tipici:

| Il tuo sistema | Valori `vendor_data` adatti |
| - | - |
| Database utenti interno | `user_1234`, `uuid-v4` dell'utente |
| ID rivolto al cliente | `CUST-2026-00042`, email con hash |
| SaaS multi-tenant | `tenant_acme:user_1234` |
| Piattaforma B2B | `company-hq-global`, `tax-id-US-123456789` |

> [!WARNING]
>
> **Non** inserire dati personali (email, numeri di telefono, identificativi fiscali in chiaro) direttamente in `vendor_data`. Applica un hash o un prefisso. `vendor_data` compare nei payload dei webhook e viene conservato a tempo indeterminato finché l'entità esiste.

## Come collega gli elementi

```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
```

Quando invii una sessione o una transazione con un valore `vendor_data`:

1. Didit cerca nella tua applicazione l'entità con quel `vendor_data`.
2. Se esiste, il nuovo oggetto viene collegato a quell'entità.
3. Se non esiste, Didit crea l'entità (con `status: ACTIVE`) e collega il nuovo oggetto.

Questo vale per:

* `POST /v3/session/`: sessioni KYC e di Verifica aziendale (KYB)
* `POST /v3/transactions/`: transazioni (sia per il richiedente sia per la controparte)
* I campi `applicant.vendor_data` / `counterparty.vendor_data` all'interno dei payload delle transazioni

## Unicità e ambito

`vendor_data` è **univoco per applicazione**, non in modo globale all'interno di Didit:

| Ambito | Garanzia di unicità |
| - | - |
| All'interno di una stessa applicazione | `vendor_data` è univoco per tipo di entità (Utente e Azienda sono namespace separati) |
| Tra applicazioni della tua organizzazione | `vendor_data` **non** è condiviso: lo stesso valore in due app si riferisce a due entità diverse |
| Tra organizzazioni | Non condiviso: ogni organizzazione ha le proprie tabelle di entità |

Ciò significa che puoi usare lo stesso `vendor_data` in un'app di staging e in un'app di produzione senza collisioni, e puoi avere un Utente `user-42` e un'Azienda `user-42` senza collisioni (anche se, per chiarezza, è sconsigliato).

## Cosa succede se ometti `vendor_data`

Puoi creare una sessione senza `vendor_data`. In questo caso:

* Non viene creata alcuna entità per la sessione.
* La sessione è orfana: non compare nel profilo di nessun Utente o Azienda.
* Non puoi cercare in seguito la sessione tramite `vendor_data`, ma solo tramite `session_id`.

Usa questo schema solo per verifiche anonime o una tantum in cui non serve alcuna aggregazione delle entità. Per ogni integrazione che prevede una nuova verifica, transazioni o monitoraggio continuo, fornisci sempre `vendor_data`.

## Esempio: crea prima un'entità, poi avvia le sessioni

```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" }
  }'
```

Tutte e tre le chiamate sono collegate alla stessa entità Utente. Quando in seguito esegui `GET /v3/users/user-42/`, vedi il numero di sessioni, i contatori delle sessioni approvate/rifiutate, le transazioni collegate e gli ultimi dati del profilo.

## Migrazione degli ID esterni

Se adotti Didit dopo aver utilizzato un fornitore KYC esistente, passa fin dal primo giorno i tuoi ID utente stabili esistenti come `vendor_data`. Così puoi facilmente:

* Riconciliare i dati di Didit con il tuo database interno.
* Caricare in blocco gli utenti storici tramite import CSV dalla console prima di avviare qualsiasi sessione.
* Preservare le relazioni quando in seguito passi a Didit per il monitoraggio delle transazioni.

## Regole, convenzioni e buone pratiche

| Regola | Perché |
| - | - |
| Scegli un unico identificatore canonico per ogni entità e non cambiarlo mai | Le modifiche creano una nuova entità e lasciano orfana la cronologia |
| Prefissa i valori `vendor_data` in base al tipo di entità (`user_...`, `biz_...`) | Evita collisioni accidentali tra namespace nel tuo codice |
| Mantieni `vendor_data` stabile e sensibile alle maiuscole | Didit non normalizza le maiuscole |
| Mantieni la lunghezza di `vendor_data` sotto i 128 caratteri | Rientra comodamente negli indici del database |
| Non esporre mai dati personali in chiaro | `vendor_data` compare nei webhook, nei registri di audit e nelle risposte API |

## Passi successivi

> [card] [Panoramica degli utenti](https://docs.didit.me/it/entities/users/overview.md)
>
> Approfondimento sulle entità Utente e sulle relative operazioni.

> [card] [Panoramica delle aziende](https://docs.didit.me/it/entities/businesses/overview.md)
>
> Approfondimento sulle entità Azienda e sulle relative operazioni.

> [card] [Crea sessione](https://docs.didit.me/it/sessions-api/create-session.md)
>
> Avvia una verifica per un vendor\_data.

> [card] [Crea transazione](https://docs.didit.me/it/management-api/transactions/create.md)
>
> Invia una transazione collegata a un'entità.


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