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

# Vinculación de vendor_data: asocia IDs a entidades

> El ID vendor_data vincula tu sistema con Didit: une sesiones, transacciones y entidades de usuario y empresa en un perfil. Pago por llamada.

Prompt de vinculación mediante vendor\_data
Copiar el prompt al portapapeles

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

Pegar en

`vendor_data` es el identificador que proporcionas en cada sesión y transacción para vincular cada una a una entidad de [usuario](https://docs.didit.me/es/entities/users/overview.md) o de [empresa](https://docs.didit.me/es/entities/businesses/overview.md). Es el campo más importante para la agregación de entidades: si lo configuras bien, todas las funciones posteriores (historial del perfil, monitorización de transacciones, aplicación de la lista de bloqueo, AML continuo) funcionan sin problemas.

## Qué es

`vendor_data` es una **cadena** que eliges tú. Didit lo trata como un identificador opaco y no interpreta su contenido. Valores habituales:

| Tu sistema | Valores adecuados de `vendor_data` |
| - | - |
| Base de datos interna de usuarios | `user_1234`, `uuid-v4` del usuario |
| ID visible para el cliente | `CUST-2026-00042`, correo electrónico con hash |
| SaaS multiinquilino | `tenant_acme:user_1234` |
| Plataforma B2B | `company-hq-global`, `tax-id-US-123456789` |

> [!WARNING]
>
> **No** incluyas datos personales identificables (correos electrónicos, números de teléfono, identificaciones fiscales sin procesar) directamente en `vendor_data`. Aplícales un hash o un prefijo. `vendor_data` aparece en los payloads de webhook y se conserva indefinidamente mientras exista la entidad.

## Cómo vincula los elementos

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

Cuando envías una sesión o una transacción con un valor de `vendor_data`:

1. Didit busca en tu aplicación la entidad con ese `vendor_data`.
2. Si existe, el nuevo objeto se vincula a esa entidad.
3. Si no existe, Didit crea la entidad (con `status: ACTIVE`) y vincula el nuevo objeto.

Esto se aplica a:

* `POST /v3/session/`: sesiones de KYC y de verificación de empresas (KYB)
* `POST /v3/transactions/`: transacciones (tanto para el solicitante como para la contraparte)
* Los campos `applicant.vendor_data` / `counterparty.vendor_data` dentro de los payloads de transacciones

## Unicidad y ámbito

`vendor_data` es **único por aplicación**, no de forma global en todo Didit:

| Ámbito | Garantía de unicidad |
| - | - |
| Dentro de una aplicación | `vendor_data` es único por tipo de entidad (usuario y empresa son espacios de nombres independientes) |
| Entre aplicaciones de tu organización | `vendor_data` **no** se comparte: el mismo valor en dos aplicaciones se refiere a dos entidades distintas |
| Entre organizaciones | No se comparte: cada organización tiene sus propias tablas de entidades |

Esto significa que puedes usar el mismo `vendor_data` en una aplicación de staging y en una de producción sin colisiones, y que puedes tener un usuario `user-42` y una empresa `user-42` sin colisión (aunque no se recomienda por motivos de claridad).

## Qué ocurre si omites `vendor_data`

Puedes crear una sesión sin `vendor_data`. En ese caso:

* No se crea ninguna entidad para la sesión.
* La sesión queda huérfana: no aparecerá en ningún perfil de usuario ni de empresa.
* Más adelante no podrás buscar la sesión por `vendor_data`, solo por `session_id`.

Usa este patrón solo para verificaciones anónimas o puntuales en las que no se necesite agregación de entidades. En cualquier integración que implique reverificación, transacciones o monitorización continua, proporciona siempre `vendor_data`.

## Ejemplo: crear una entidad por adelantado y después ejecutar sesiones

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

Las tres llamadas quedan vinculadas a la misma entidad de usuario. Cuando más adelante ejecutes `GET /v3/users/user-42/`, verás el número de sesiones, los contadores de aprobadas y rechazadas, las transacciones vinculadas y los datos de perfil más recientes.

## Migración de ID externos de usuarios

Si adoptas Didit después de haber usado otro proveedor de KYC, pasa tus ID de usuario estables existentes como `vendor_data` desde el primer día. Así te resultará fácil:

* Conciliar los datos de Didit con tu base de datos interna.
* Cargar de forma masiva usuarios históricos mediante la importación CSV de la consola antes de ejecutar cualquier sesión.
* Conservar las relaciones cuando más adelante migres a Didit para la monitorización de transacciones.

## Reglas, convenciones y buenas prácticas

| Regla | Motivo |
| - | - |
| Elige un identificador canónico por entidad y no lo cambies nunca | Los cambios crean una entidad nueva y dejan huérfano el historial |
| Añade a los valores de `vendor_data` un prefijo según el tipo de entidad (`user_...`, `biz_...`) | Evita colisiones accidentales entre espacios de nombres en tu propio código |
| Mantén estable el uso de mayúsculas y minúsculas en `vendor_data` | Didit no normaliza mayúsculas y minúsculas |
| Mantén la longitud de `vendor_data` por debajo de 128 caracteres | Cabe holgadamente en los índices de base de datos |
| No expongas nunca datos personales identificables sin procesar | `vendor_data` aparece en webhooks, registros de auditoría y respuestas de la API |

## Próximos pasos

> [card] [Visión general de usuarios](https://docs.didit.me/es/entities/users/overview.md)
>
> Análisis detallado de las entidades de usuario y sus operaciones.

> [card] [Visión general de empresas](https://docs.didit.me/es/entities/businesses/overview.md)
>
> Análisis detallado de las entidades de empresa y sus operaciones.

> [card] [Crear sesión](https://docs.didit.me/es/sessions-api/create-session.md)
>
> Inicia una verificación para un dato de proveedor.

> [card] [Crear transacción](https://docs.didit.me/es/management-api/transactions/create.md)
>
> Envía una transacción vinculada a una entidad.


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