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

# Liaison des données fournisseur aux entités

> L'identifiant vendor_data relie votre système à Didit : sessions, transactions et entités Utilisateur/Entreprise forment un seul profil. Facturation à l'appel.

Prompt de liaison vendor\_data
Copier le prompt dans le presse-papiers

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

Coller dans

`vendor_data` est l'identifiant que vous fournissez pour chaque session et chaque transaction afin de le lier à une entité [Utilisateur](https://docs.didit.me/fr/entities/users/overview.md) ou [Entreprise](https://docs.didit.me/fr/entities/businesses/overview.md). C'est le champ le plus important pour l'agrégation des entités : s'il est correct, toutes les fonctionnalités en aval (historique du profil, surveillance des transactions, application des listes de blocage, surveillance AML continue) fonctionnent de manière fluide.

## Ce que c'est

`vendor_data` est une **chaîne de caractères** que vous choisissez. Didit le traite comme un identifiant opaque et n'interprète pas son contenu. Exemples de valeurs courantes :

| Votre système | Valeurs `vendor_data` adaptées |
| - | - |
| Base de données interne des utilisateurs | `user_1234`, `uuid-v4` de l'utilisateur |
| Identifiant côté client | `CUST-2026-00042`, e-mail haché |
| SaaS multi-locataires | `tenant_acme:user_1234` |
| Plateforme B2B | `company-hq-global`, `tax-id-US-123456789` |

> [!WARNING]
>
> Ne mettez **jamais** de données personnelles (e-mails, numéros de téléphone, identifiants fiscaux en clair) directement dans `vendor_data`. Hachez-les ou ajoutez-leur un préfixe. `vendor_data` apparaît dans les payloads des webhooks et est conservé indéfiniment tant que l'entité existe.

## Comment il relie les éléments entre eux

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

Lorsque vous soumettez une session ou une transaction avec une valeur `vendor_data` :

1. Didit recherche dans votre application l'entité associée à ce `vendor_data`.
2. Si elle existe, le nouvel objet y est lié.
3. Si elle n'existe pas, Didit crée l'entité (avec `status: ACTIVE`) et y lie le nouvel objet.

Cela s'applique à :

* `POST /v3/session/` : sessions de vérification d'identité (KYC) et de vérification d'entreprise (KYB)
* `POST /v3/transactions/` : transactions (pour le demandeur comme pour la contrepartie)
* Les champs `applicant.vendor_data` et `counterparty.vendor_data` dans les payloads des transactions

## Unicité et portée

`vendor_data` est **unique par application**, et non à l'échelle de Didit tout entier :

| Portée | Garantie d'unicité |
| - | - |
| Au sein d'une application | `vendor_data` est unique par type d'entité (Utilisateur et Entreprise sont des espaces de noms distincts) |
| Entre les applications de votre organisation | `vendor_data` n'est **pas** partagé : la même valeur dans deux applications désigne deux entités différentes |
| Entre les organisations | Non partagé : chaque organisation dispose de ses propres tables d'entités |

Vous pouvez donc utiliser la même valeur `vendor_data` dans une application de préproduction et une application de production sans conflit. Vous pouvez aussi avoir un Utilisateur `user-42` et une Entreprise `user-42` sans conflit, bien que ce soit déconseillé pour la clarté.

## Ce qui se passe si vous omettez `vendor_data`

Vous pouvez créer une session sans `vendor_data`. Dans ce cas :

* Aucune entité n'est créée pour la session.
* La session est orpheline : elle n'apparaît dans aucun profil d'Utilisateur ou d'Entreprise.
* Vous ne pourrez pas retrouver la session ultérieurement par `vendor_data`, seulement par `session_id`.

N'utilisez ce schéma que pour des vérifications anonymes ou ponctuelles qui ne nécessitent aucune agrégation d'entités. Pour toute intégration impliquant une revérification, des transactions ou une surveillance continue, fournissez toujours `vendor_data`.

## Exemple : créer une entité à l'avance, puis lancer des sessions

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

Les trois appels sont liés à la même entité Utilisateur. Lorsque vous appellerez ensuite `GET /v3/users/user-42/`, vous verrez le nombre de sessions, les compteurs d'approbations et de refus, les transactions liées et les dernières données du profil.

## Migrer des identifiants externes

Si vous adoptez Didit après un fournisseur KYC existant, transmettez dès le départ vos identifiants utilisateur stables existants comme `vendor_data`. Cela vous permet de :

* Rapprocher les données de Didit avec votre base de données interne.
* Importer en masse les utilisateurs historiques via l'import CSV de la console avant de lancer la moindre session.
* Préserver les relations lorsque vous migrerez plus tard vers Didit pour la surveillance des transactions.

## Règles, conventions et bonnes pratiques

| Règle | Pourquoi |
| - | - |
| Choisissez un identifiant canonique par entité et ne le modifiez jamais | Un changement crée une nouvelle entité et rend l'historique orphelin |
| Préfixez les valeurs `vendor_data` par type d'entité (`user_...`, `biz_...`) | Évite les collisions accidentelles entre espaces de noms dans votre propre code |
| Gardez `vendor_data` stable et sensible à la casse | Didit ne normalise pas la casse |
| Gardez `vendor_data` d'une longueur inférieure à 128 caractères | Tient confortablement dans les index de base de données |
| N'exposez jamais de données personnelles en clair | `vendor_data` apparaît dans les webhooks, les journaux d'audit et les réponses de l'API |

## Étapes suivantes

> [card] [Vue d'ensemble des utilisateurs](https://docs.didit.me/fr/entities/users/overview.md)
>
> Présentation détaillée des entités Utilisateur et de leurs opérations.

> [card] [Vue d'ensemble des entreprises](https://docs.didit.me/fr/entities/businesses/overview.md)
>
> Présentation détaillée des entités Entreprise et de leurs opérations.

> [card] [Créer une session](https://docs.didit.me/fr/sessions-api/create-session.md)
>
> Lancer une vérification pour un vendor\_data.

> [card] [Créer une transaction](https://docs.didit.me/fr/management-api/transactions/create.md)
>
> Soumettre une transaction liée à une entité.


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