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

# API de personas clave KYB: UBO, directores y directivos

> Didit verifica UBO, accionistas, directores y directivos en un flujo KYB con sesiones KYC vinculadas. Desde $2.00 por verificación, sin contratos.

**Personas clave** es el modelo unificado de Didit para cada persona física y entidad jurídica vinculada a la empresa que verificas: UBO, accionistas (personas físicas y jurídicas), directores, representantes y otros cargos. Un único flujo de Personas clave lo cubre todo, con una asignación de la verificación según el rol y una comparación completa, lado a lado, entre las partes obtenidas del registro y las que envía el usuario.

> [!NOTE]
>
> Para ver las personas clave por entidad empresarial, es decir, cómo se agrupan los directivos y los UBO entre sesiones, consulta [Empresas → Personas clave](https://docs.didit.me/es/entities/businesses/key-people.md).

## Cómo funciona

**1. Rellenado previo desde el registro (opcional)**

Si el flujo de verificación (workflow) tiene activado el rellenado previo desde el registro, la pantalla de Personas clave se completa de antemano con los UBO, accionistas y directivos disponibles extraídos de la comprobación en el registro.
El usuario final puede editar, añadir o eliminar personas o entidades antes de enviarlas, incluso cuando la información de propiedad aún está pendiente.
Los directivos recibidos hasta el momento siguen disponibles mientras se obtiene el informe de propiedad.
Antes del envío, los resultados que llegan tarde rellenan los campos no modificados y añaden las personas que faltan, sin sustituir las ediciones ni restaurar las personas o entidades eliminadas.
Un editor abierto no cambia; el rellenado previo adicional se aplica cuando el solicitante lo cierra.
Con el rellenado previo desde el registro desactivado, los solicitantes introducen las personas por su cuenta y los resultados que llegan tarde no completan este formulario.
Los datos del registro que llegan después del envío siguen formando parte de la evidencia del registro, pero no modifican la lista de personas enviada ni crean automáticamente sesiones de verificación secundarias adicionales.

**2. Envío desde el flujo alojado**

El usuario final envía la lista definitiva de personas clave a través del flujo de verificación alojado. De forma predeterminada no necesitas realizar este paso tú mismo: se lleva a cabo dentro del flujo de KYB cuya URL proporcionaste mediante [Crear sesión](https://docs.didit.me/es/sessions-api/create-session.md).
Si prefieres mantener tu propio front end, usa los endpoints de [borrador de personas o entidades](https://docs.didit.me/es/sessions-api/kyb-create-party-draft.md) y [envío de personas o entidades](https://docs.didit.me/es/sessions-api/kyb-submit-parties.md).

**3. Enrutamiento de la verificación según el rol**

Para cada persona o entidad enviada, Didit comprueba la configuración de verificación del rol:

* Aplica el umbral de propiedad del flujo: los UBO y accionistas por debajo del porcentaje configurado no requieren verificación individual.
* Respeta la marca de "omitir verificación" que haya indicado el usuario final, si el rol permite omitirla.
* Crea una sesión secundaria de Verificación de usuarios (KYC) para las personas físicas que requieren KYC.
* Crea una subsesión secundaria de KYB para los UBO que son personas jurídicas cuando el KYB anidado está activado en el flujo.

**4. Evolución del estado**

El estado de la función Personas clave pasa a `Awaiting User` mientras alguna sesión secundaria obligatoria siga en curso. Cuando terminan todas las sesiones secundarias, el estado se establece en `Approved`, `Declined` o `In Review` según los resultados.

## Roles recopilados

Las personas clave pueden tener uno o varios de los siguientes roles; una misma persona puede ocupar varios a la vez (por ejemplo, director **y** accionista). La taxonomía completa es la siguiente:

| Categoría | Roles |
| - | - |
| **Propiedad** | `ubo`, `shareholder`, `beneficiary`, `settlor`, `protector`, `investor` |
| **Gobierno / representación** | `director`, `non_executive_director`, `chairman`, `secretary`, `representative`, `authorized_signatory`, `trustee`, `company_officer`, `founder`, `legal_advisor`, `other` |

Cada rol se puede configurar de forma individual en el flujo: activado o desactivado, obligatorio u opcional para KYC, asociado a un flujo de KYC concreto y, opcionalmente, omitible. Consulta [Propiedad](https://docs.didit.me/es/business-verification/ownership.md) para conocer los detalles de la asignación de la verificación.

## Datos recopilados por persona clave

El flujo alojado solicita un conjunto de campos predeterminado y campos personalizados adicionales configurados en el flujo de trabajo. Consulta [Propiedad → Campos recopilados](https://docs.didit.me/es/business-verification/ownership.md#datos-recopilados-de-cada-persona-clave) para ver la lista completa.

## Confirmación del registro

Antes del paso de Personas clave, el usuario final revisa los datos de la empresa extraídos de la comprobación en el registro y, si lo desea, edita cualquier campo. A continuación, el flujo alojado almacena:

* El **detalle del registro** que Didit normalizó a partir de la comprobación en el registro (`registry_data`).
* Los **datos confirmados por el usuario** (`user_provided_data`), con una marca de tiempo que indica cuándo los confirmó.
* Una vista canónica combinada de los campos de nivel superior de la empresa: los datos confirmados por el usuario cuando existen y, en caso contrario, los del registro.

Consulta [Datos de la empresa → Datos del registro frente a datos proporcionados por el usuario](https://docs.didit.me/es/business-verification/company-data.md#datos-del-registro-frente-a-datos-proporcionados-por-el-usuario) para ver el modelo completo.

## Estructura en la respuesta de decisión

Tras el envío, las personas clave recopiladas aparecen en la decisión de KYB en `key_people_checks[]`, divididas en dos grupos: **registry** (lo que divulgó el proveedor) y **submitted** (lo que el administrador de la empresa confirmó a través del flujo), además de un `ubo_kyc_summary` que resume el progreso del KYC de los UBO. Consulta la [referencia completa de key\_people\_checks](https://docs.didit.me/es/business-verification/response-schema.md#key_people_checks).

## Comportamiento al reenviar

* **Personas clave** y **Comprobación en el registro** no se pueden reenviar directamente. Para volver a verificar a una persona concreta, reenvía su sesión de KYC secundaria individual.
* Cuando se reenvía una sesión de KYC secundaria, el estado de la función Personas clave principal vuelve automáticamente a `Awaiting User`.
* Cuando termina la sesión secundaria reenviada, la función principal vuelve a calcularse según los estados de todas las sesiones secundarias.
* Una sesión secundaria que se eliminó, o que expiró antes de que la persona la iniciara, no se puede reenviar: [regenera la parte](https://docs.didit.me/es/sessions-api/regenerate-kyb-party.md) para emitir un nuevo enlace en la misma parte.

## Cuánto dura el enlace de verificación de una persona clave

La sesión KYC secundaria de una persona clave sigue el tiempo de expiración de sesión del flujo KYC configurado para su rol, no el del flujo KYB. Si asignas a un rol un flujo KYC que permite cuatro semanas, el enlace de esa persona sigue siendo utilizable durante cuatro semanas, aunque la sesión de la empresa esté configurada para expirar antes.

El valor es una configuración de cada flujo, de 1 hora a 4 semanas (`session_expiration_time`, en segundos), en *Workflows → \[flujo KYC] → Settings*.

La expiración cambia lo que puedes hacer con la persona. Un enlace que expiró antes de que la persona empezara, al igual que uno cuya sesión se eliminó, puede volver a emitirse con [Regenerate Key People KYC Session](https://docs.didit.me/es/sessions-api/regenerate-kyb-party.md). Las sesiones eliminadas cumplen los requisitos aunque la persona ya hubiera empezado o terminado la verificación. Las sesiones importadas no cumplen los requisitos por expiración; deben haberse eliminado. Una sesión que no se ha eliminado y que la persona ya había empezado no cumple los requisitos por expiración.

## Opciones de configuración

Todo el comportamiento de personas clave se configura por flujo desde la Business Console:

| Configuración | Qué controla |
| - | - |
| **Registry prefill** | Rellena previamente el formulario de personas clave con datos del registro |
| **Extra fields — persons** | Campos personalizados que se recopilan para cada parte individual |
| **Extra fields — companies** | Campos personalizados que se recopilan para cada parte corporativa |
| **Umbral de propiedad de UBO** | Porcentaje mínimo de propiedad para clasificar a alguien como UBO |
| **Umbral de propiedad de accionista** | Porcentaje mínimo de propiedad para clasificar a alguien como accionista |
| **Per-role settings** | Para cada rol: activado/desactivado, exigir KYC, flujo KYC que se usa, se puede omitir |
| **Corporate UBO nested KYB** | Si está activado, los UBO corporativos generan su propia sesión KYB secundaria |
| **Reutilizar individuos verificados** | Consulta [Reutilizar individuos verificados entre verificaciones KYB](#reutilizar-individuos-verificados-entre-verificaciones-kyb) más abajo |
| **Notificar a las partes por correo electrónico** | Envía automáticamente por correo electrónico a cada persona clave su enlace de verificación |

Configura estas opciones en *Workflows → \[flujo KYB] → Key People* en la consola.

## Reutilizar individuos verificados entre verificaciones KYB

Cuando **Reutilizar individuos verificados** está activado en un flujo (valor predeterminado), una persona clave no tiene que repetir el KYC cada vez que aparece en una nueva verificación KYB. Didit busca un KYC aprobado existente de una verificación KYB anterior y lo vincula a la nueva parte en lugar de crear una nueva sesión KYC hija.

> [!NOTE]
>
> Es un mecanismo distinto de [KYC reutilizable](https://docs.didit.me/es/core-technology/reusable-kyc/overview.md), que permite a un *usuario final* llevar voluntariamente una sesión finalizada entre distintas aplicaciones integradas con Didit mediante un token para compartir/importar. La opción de reutilización KYB de esta página es automática, se configura en el flujo y se limita a las personas clave dentro de una sola aplicación: sin token de compartir y sin ninguna acción del usuario final.

**Coincidencia.** Se identifica una posible coincidencia comparando el nombre completo de la persona proporcionada (sin distinguir mayúsculas y minúsculas y sin espacios al inicio ni al final) con las personas clave de las demás verificaciones KYB de la aplicación. No hay ninguna señal de coincidencia adicional: no se exige ni se comprueba que coincida el número de documento, el correo electrónico o el teléfono. Un nombre escrito con otra ortografía, con un segundo nombre o con una transliteración no coincidirá y, en casos excepcionales, dos personas distintas con el mismo nombre podrían coincidir; ten esto en cuenta al revisar tus resultados de personas clave.

**Alcance.** La búsqueda de coincidencias abarca todas las demás verificaciones KYB que pertenecen a la *misma aplicación*, no solo la verificación KYB actual, y no otras aplicaciones de tu organización. Una persona verificada como UBO en la empresa A puede coincidir cuando aparece más tarde como director en la empresa B, siempre que ambas verificaciones se ejecuten en la misma aplicación.

**Estados admitidos.** Solo el KYC **Aprobado** más reciente de una parte puede reutilizarse. Un KYC **Rechazado** para ese nombre bloquea por completo la reutilización: la parte se marca y se solicita un nuevo KYC en lugar de recurrir al rechazado. Un KYC que sigue **En Revisión** nunca se considera candidato.

**Retención.** La búsqueda de coincidencias solo tiene en cuenta las sesiones KYC creadas aproximadamente en el último año que no se hayan eliminado. Si la única sesión coincidente queda fuera de ese periodo, o la persona o la organización la han eliminado, la verificación no encuentra ninguna coincidencia válida y solicita un nuevo KYC sin avisar: nunca falla ni bloquea el envío de personas clave.

**Facturación.** Un KYC reutilizado no se vuelve a facturar. Vincular una sesión ya aprobada a la nueva parte no tiene ningún coste adicional; solo se te factura una vez, por el KYC original.

```txt Example theme={null}
Company A: Jane Doe submitted as UBO, KYC approved.
Company B (same application): Jane Doe submitted as a director.
"Reuse verified individuals" is enabled, so Company B's Key People
check links Jane's existing approved KYC instead of requesting a
new one - free, and instantly Approved for that party.
```

## Próximos pasos

> [card] [Propiedad](https://docs.didit.me/es/business-verification/ownership.md)
>
> Campos recopilados, datos personalizados y conciliación entre los datos del registro y los enviados.

> [card] [Directivos y representantes](https://docs.didit.me/es/business-verification/officers.md)
>
> Roles de gobernanza dentro del modelo de personas clave.

> [card] [Esquema de respuesta](https://docs.didit.me/es/business-verification/response-schema.md#key_people_checks)
>
> Referencia campo por campo de `key_people_checks[]`.


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