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

# Operaciones de usuarios: CRUD de usuarios del proveedor

> Crea, consulta, actualiza, cambia el estado y elimina entidades User de Didit con la Management API. Pago por uso, sin contratos.



Prompt de operaciones de usuarios
        Copiar el prompt al portapapeles



      
      

\<pre>

\````# Goal — full CRUD over Didit User entities

Core CRUD operations sit under `https://verification.didit.me/v3/users/` authenticated with `x-api-key: $DIDIT_API_KEY`. Profile attachment endpoints use the organization/application path and the User's `didit_internal_id`. Each User is keyed by `vendor_data` (case-sensitive, unique per application).

\## Endpoint catalog

\| Action | Method + path |
\|---|---|
\| List users | `GET /v3/users/` |
\| Get one user | `GET /v3/users/{vendor_data}/` |
\| Create user | `POST /v3/users/create/` |
\| Upload profile face | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` |
\| Update profile | `PATCH /v3/users/{vendor_data}/` |
\| Change status | `PATCH /v3/users/{vendor_data}/update-status/` |
\| Batch delete | `POST /v3/users/delete/` |

\## List (with filters)

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

\## Get one user

\```bash
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

\## Create

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

Not idempotent — retrying with the same `vendor_data` returns conflict. `GET` first or PATCH instead.

\## Upload an imported profile face

\```bash
\# First read didit_internal_id from GET /v3/users/{vendor_data}/
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: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

This attaches a trusted face image to the User profile and enrolls it for duplicate detection and face search. It does not add the face to a blocklist.

\## Update profile

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

Mutable: `display_name`, `metadata`, `tags`. Read-only (verified): `full_name`, `date_of_birth`, `portrait_image`, all aggregate counters, `features` map.

\## Change status

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

Valid statuses: `ACTIVE`, `FLAGGED`, `BLOCKED`. `BLOCKED` users have new sessions auto-declined.

\## Batch delete

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

Idempotent — already-deleted is a no-op. Returns a count, `{"deleted": <int>}`, not a per-item result. The user records and every biometric template retained for them are removed permanently. Verification sessions are not covered by this endpoint; delete those with the session delete endpoints.

\## Webhooks fired

\| Operation | Event |
\|---|---|
\| create | none for the create call itself — the first `user.data.updated` arrives when a session or a PATCH first fills the profile |
\| update (PATCH) | `user.data.updated` with `changed_fields` |
\| update-status | `user.status.updated` |
\| delete | none — record the deletion on your own side if you need to react to it |

\## Failure modes

\- `401` — missing / invalid `x-api-key`.
\- `403` — the API key is not valid for this application.
\- `409` on create — `vendor_data` already exists; switch to PATCH.
\- `404` — no entity for that `vendor_data` (case-sensitive!).
\- `429` — rate-limited; back off using `Retry-After`.

\## Response shape

See /reference/data-models and /entities/users/data-model for the full User schema.

\## Sources of truth

\- /management-api/users/list, /management-api/users/get, /management-api/users/create — per-endpoint reference
\- /entities/users/data-model — field-by-field schema
\- /entities/webhooks — entity event payloads
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Pegar en

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](https://docs.didit.me/es/management-api/users/list.md) 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.```bash theme={null}
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](https://docs.didit.me/es/entities/users/data-model.md) completo, incluidos los contadores agregados.```bash theme={null}
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
```> [!NOTE]
>
> `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.```bash theme={null}
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](https://docs.didit.me/es/management-api/users/create.md#enviar-un-enlace-de-verificación) 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.```bash theme={null}
# 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](https://docs.didit.me/es/management-api/users/upload-face.md) 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`.```bash theme={null}
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.```bash theme={null}
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](https://docs.didit.me/es/management-api/biometric-templates/overview.md) 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](https://docs.didit.me/es/sessions-api/delete-session.md) o [Batch Delete Sessions](https://docs.didit.me/es/management-api/sessions/batch-delete.md). Las transacciones tampoco se incluyen; elimínalas desde la Console.```bash theme={null}
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 permisosLas 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](https://docs.didit.me/es/console/api-keys.md) 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](https://docs.didit.me/es/console/roles-permissions.md) 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](https://docs.didit.me/es/integration/rate-limiting.md) 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> [card] [Modelo de datos](https://docs.didit.me/es/entities/users/data-model.md)
>
> Referencia completa de campos.> [card] [API de listado](https://docs.didit.me/es/management-api/users/list.md)
>
> Esquema de GET /v3/users/.> [card] [API de creación](https://docs.didit.me/es/management-api/users/create.md)
>
> Esquema de POST /v3/users/create/.> [card] [Subir imágenes faciales](https://docs.didit.me/es/management-api/users/upload-face.md)
>
> Adjunta imágenes faciales importadas a los perfiles de usuario.


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