Operaciones de usuarios: CRUD de usuarios del proveedor

La gestión principal de la entidad User se realiza a través de endpoints públicos bajo /v3/users/. Los adjuntos del perfil, como la carga de un rostro importado, usan la ruta de organización/aplicación con didit_internal_id. Esta página ofrece un recorrido conceptual; consulta la referencia de la API para ver los esquemas completos de solicitud y respuesta.

Listar usuarios

GET /v3/users/ Devuelve una lista paginada de los usuarios de tu aplicación. Admite filtros por estado, búsqueda, rango de fechas y más.

curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"

Casos de uso:

Sincronizar cada día un subconjunto de usuarios con tu almacén de datos.
Encontrar usuarios marcados para una cola de analistas.
Buscar usuarios por nombre para mostrar.

Obtener un usuario

GET /v3/users/{vendor_data}/ Recupera un único usuario por vendor_data. Devuelve el modelo de datos completo, incluidos los contadores agregados.

curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"

vendor_data en la URL distingue entre mayúsculas y minúsculas. Envía siempre el valor exacto que usaste al crear la sesión.

Crear un usuario

POST /v3/users/create/ Crea una entidad User antes de que se inicie cualquier sesión. Resulta útil para:

Precargar metadatos o campos personalizados antes de que el cliente se verifique.
Establecer un estado inicial (por ejemplo, FLAGGED mientras tu equipo de onboarding revisa documentos manualmente).
Precargar usuarios desde una base de datos existente para tener un listado completo desde el primer día.

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_source": "web" }
  }'

Si ya existe un usuario con ese vendor_data, la solicitud devuelve un error de conflicto; usa PATCH para actualizarlo. También puedes enviar datos de contacto: first_name y last_name (se unen en full_name si no envías uno), email, phone_number y country. Didit guarda email y phone_number en metadata.contact, y country en metadata.address. Para invitar a la persona a verificarse en la misma solicitud, añade send_verification_link: true junto con un email y un workflow_id. Didit crea una sesión de verificación para la persona en ese flujo de verificación (workflow) y le envía el enlace por correo electrónico. El campo verification_link de la respuesta contiene session_id, session_number, status, url, workflow_id y email de la sesión, y es null cuando no solicitas un enlace. Consulta Create User para ver las comprobaciones y los errores.

Subir un rostro importado

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ Adjunta una imagen facial de confianza a un perfil de usuario existente. Es el paso siguiente adecuado cuando importas usuarios desde otro proveedor y quieres que Didit conserve su evidencia facial antes de la primera sesión en Didit.

# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'

Consulta Upload User Face para ver los campos de la solicitud, los límites, los endpoints para listar y eliminar, y la diferencia con la lista de bloqueo.

Actualizar un usuario

PATCH /v3/users/{vendor_data}/ Actualiza los campos modificables del perfil. La mayoría de los campos derivados de sesiones verificadas son de solo lectura: si intentas cambiarlos mediante PATCH, el cambio se ignorará o quedará marcado en el registro de auditoría. Campos modificables: display_name, metadata, tags. De solo lectura tras la verificación: full_name, date_of_birth, portrait_image, todos los contadores agregados y el mapa features.

curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'

Emite un webhook user.data.updated con el array changed_fields.

Cambiar el estado

PATCH /v3/users/{vendor_data}/update-status/ Mueve un usuario entre ACTIVE, FLAGGED y BLOCKED. Los cambios de estado se aplican a las sesiones y transacciones futuras.

curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'

De → a	Disparador habitual
`ACTIVE` → `FLAGGED`	Regla de transacciones, revisión de un analista, coincidencia en la monitorización continua de AML
`ACTIVE` → `BLOCKED`	Fraude confirmado, sesión rechazada con bloqueo automático, coincidencia en la lista de bloqueo
`FLAGGED` → `ACTIVE`	Un analista concluyó la revisión
`BLOCKED` → `ACTIVE`	Desbloqueo manual por parte de un analista

Emite un webhook user.status.updated.

Eliminar usuarios (en lote)

POST /v3/users/delete/ Elimina uno o varios usuarios. Los registros de usuario se eliminan de forma permanente, junto con todas las plantillas biométricas conservadas para ellos tras la eliminación de sesiones. Sus sesiones de verificación no se incluyen en este endpoint y se conservan, pero sin su vínculo con el usuario; elimínalas con Delete Session o Batch Delete Sessions. Las transacciones tampoco se incluyen; elimínalas desde la Console.

curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'

Selecciona usuarios por vendor_data_list, por didit_internal_id_list o por ambos a la vez; o envía delete_all: true para eliminar todos los usuarios de la aplicación. Los parámetros de lote filter_* de la Console se rechazan aquí con un 400 en lugar de ignorarse, de modo que una intención acotada nunca pueda convertirse en un borrado total. Devuelve un recuento, {"deleted": <int>}, no un resultado por elemento. Los identificadores que no coinciden con nada se omiten sin aviso, así que envía una lista sin duplicados si quieres comparar deleted con el número de identificadores que enviaste.

Modelo de permisos

Las claves de API pertenecen a una sola aplicación. El secreto principal y las claves de acceso completo pueden llamar a todos los endpoints /v3/users/* de esa aplicación, incluido delete. Una clave de API con alcance limitado necesita acceso a People (users): lectura para los endpoints GET, y escritura para crear, actualizar, cambiar el estado y eliminar. Crear un usuario con send_verification_link: true también requiere escritura en Sessions, porque crea una sesión y envía su enlace por correo electrónico. Una clave sin el acceso necesario devuelve 403. Una clave limitada a determinados flujos o a sesiones aprobadas no puede acceder en absoluto a los endpoints /v3/users/*. Los roles son un concepto de la Console: el recurso de permisos users y sus claims determinan lo que un miembro del equipo puede hacer en la Console, y no se evalúan en las solicitudes con clave de API. Consulta Roles y permisos para ver esa matriz. Para impedir que un servicio elimine usuarios, dale una clave con acceso de solo lectura a People, o sin acceso a People.

Límites de solicitudes e idempotencia

Todos los endpoints /v3/users/* están sujetos a los límites de solicitudes estándar.
create no es idempotente: reintentar con el mismo vendor_data devuelve un conflicto. Elimina duplicados por tu lado o haz siempre un GET primero.
delete es idempotente: eliminar un usuario ya eliminado no tiene ningún efecto.

Webhooks activados por estas operaciones

Operación	Webhook
`create`	ninguno por la propia llamada de creación: el primer `user.data.updated` llega cuando una sesión o una actualización rellena el perfil por primera vez
`update`	`user.data.updated` (con `changed_fields`)
`update-status`	`user.status.updated`
`delete`	ninguno: registra la eliminación por tu cuenta si necesitas reaccionar a ella

Próximos pasos

Modelo de datos

Referencia completa de campos.

API de listado

Esquema de GET /v3/users/.

API de creación

Esquema de POST /v3/users/create/.

Subir imágenes faciales

Adjunta imágenes faciales importadas a los perfiles de usuario.

Visión general

Precios

Flujos y verificación

Revisión y operaciones

Entidades (usuarios y empresas)

Ajustes y personalización

Seguridad y cumplimiento

Didit Academy

Recursos

Operaciones de usuarios: CRUD de usuarios del proveedor

Listar usuarios

Obtener un usuario

Crear un usuario

Subir un rostro importado

Actualizar un usuario

Cambiar el estado

Eliminar usuarios (en lote)

Modelo de permisos

Límites de solicitudes e idempotencia

Webhooks activados por estas operaciones

Próximos pasos

Modelo de datos

API de listado

API de creación

Subir imágenes faciales

​Listar usuarios

​Obtener un usuario

​Crear un usuario

​Subir un rostro importado

​Actualizar un usuario

​Cambiar el estado

​Eliminar usuarios (en lote)

​Modelo de permisos

​Límites de solicitudes e idempotencia

​Webhooks activados por estas operaciones

​Próximos pasos

Modelo de datos

API de listado

API de creación

Subir imágenes faciales

Listar usuarios

Obtener un usuario

Crear un usuario

Subir un rostro importado

Actualizar un usuario

Cambiar el estado

Eliminar usuarios (en lote)

Modelo de permisos

Límites de solicitudes e idempotencia

Webhooks activados por estas operaciones

Próximos pasos