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

# Gestió d'usuaris: operacions CRUD d'usuaris del proveïdor

> Crea, consulta, actualitza, canvia l'estat i elimina entitats d'usuari de Didit mitjançant l'API de gestió. Preu per ús, sense contractes.



Prompt d'operacions d'usuaris
        Copia el prompt al porta-retalls



      
      

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



      
      

Enganxa a

Les operacions sobre l'entitat bàsica d'usuari es fan amb endpoints públics sota `/v3/users/`. Els adjunts del perfil, com la pujada d'una imatge facial importada, usen la ruta d'organització i aplicació amb `didit_internal_id`. Aquesta pàgina és una guia conceptual: consulta la [referència de l'API](https://docs.didit.me/ca/management-api/users/list.md) per als esquemes complets de sol·licitud i resposta.## Llistar usuaris**`GET /v3/users/`**Retorna una llista paginada dels usuaris de la teva aplicació. Admet filtres per estat, cerca, interval de dates i 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 d'ús:- Sincronitzar cada dia un subconjunt d'usuaris amb el teu magatzem de dades.
- Trobar usuaris marcats per a una cua d'analistes.
- Cercar usuaris pel nom visible.## Obtenir un usuari**`GET /v3/users/{vendor_data}/`**Recupera un sol usuari pel seu `vendor_data`. Retorna el [model de dades](https://docs.didit.me/ca/entities/users/data-model.md) complet, inclosos els comptadors agregats.```bash theme={null}
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
```> [!NOTE]
>
> `vendor_data` a la URL distingeix entre majúscules i minúscules. Passa sempre el valor exacte que vas fer servir en crear la sessió.## Crear un usuari**`POST /v3/users/create/`**Crea una entitat d'usuari abans que s'executi cap sessió. És útil per a:- Carregar metadades o camps personalitzats abans que el client es verifiqui.
- Establir un estat inicial (per exemple, `FLAGGED` mentre el teu equip d'alta revisa documents manualment).
- Precarregar usuaris d'una base de dades existent perquè tinguis un llistat complet des del primer dia.```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 ja existeix un usuari amb aquest `vendor_data`, la crida retorna un error de conflicte: usa `PATCH` per actualitzar-lo.També pots enviar dades de contacte: `first_name` i `last_name` (que es combinen per formar `full_name` quan no l'envies), `email`, `phone_number` i `country`.
Didit guarda `email` i `phone_number` a `metadata.contact`, i `country` a `metadata.address`.Per convidar la persona a verificar-se en la mateixa crida, afegeix `send_verification_link: true` amb un `email` i un `workflow_id`.
Didit crea per a la persona una sessió de verificació en aquell flux de treball i li envia l'enllaç per correu electrònic.
El `verification_link` de la resposta conté `session_id`, `session_number`, `status`, `url`, `workflow_id` i `email` de la sessió, i és `null` quan no en demanes cap.
Consulta [Crear usuari](https://docs.didit.me/ca/management-api/users/create.md#envia-un-enllaç-de-verificació) per a les comprovacions i els errors.## Pujar una imatge facial importada**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**Adjunta una imatge facial de confiança a un perfil d'usuari existent. És el pas adequat quan importes usuaris d'un altre proveïdor i vols que Didit incorpori la seva evidència facial abans de la primera sessió de 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 [Pujar la imatge facial d'un usuari](https://docs.didit.me/ca/management-api/users/upload-face.md) per als camps de la sol·licitud, els límits, els endpoints de llistat i eliminació, i la diferència respecte a la llista de bloqueig.## Actualitzar un usuari**`PATCH /v3/users/{vendor_data}/`**Actualitza els camps de perfil modificables. La majoria de camps derivats de sessions verificades són de només lectura: si intentes canviar-los amb PATCH, s'ignoraran o es marcaran al registre d'auditoria.**Camps modificables:** `display_name`, `metadata`, `tags`.
**De només lectura després de la verificació:** `full_name`, `date_of_birth`, `portrait_image`, tots els comptadors agregats i 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" } }'
```Emet un webhook `user.data.updated` amb la matriu `changed_fields`.## Canviar l'estat**`PATCH /v3/users/{vendor_data}/update-status/`**Mou un usuari entre `ACTIVE`, `FLAGGED` i `BLOCKED`. Els canvis d'estat es propaguen a les sessions i transaccions futures.```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 | Desencadenant habitual |
| - | - |
| `ACTIVE` → `FLAGGED` | Regla de transacció, revisió d'un analista, coincidència en el monitoratge AML continu |
| `ACTIVE` → `BLOCKED` | Frau confirmat, entrada manual a la llista de bloqueig, coincidència amb la llista de bloqueig |
| `FLAGGED` → `ACTIVE` | Revisió resolta per un analista |
| `BLOCKED` → `ACTIVE` | Desbloqueig manual per un analista |Emet un webhook `user.status.updated`.## Eliminar usuaris (en lot)**`POST /v3/users/delete/`**Elimina un o diversos usuaris. Els registres d'usuari s'eliminen de manera permanent, juntament amb totes les [plantilles biomètriques](https://docs.didit.me/ca/management-api/biometric-templates/overview.md) conservades per a ells després de l'eliminació de la sessió. Les seves sessions de verificació no les cobreix aquest endpoint i es conserven amb l'enllaç a l'usuari esborrat; elimina-les amb [Eliminar sessió](https://docs.didit.me/ca/sessions-api/delete-session.md) o [Eliminar sessions en lot](https://docs.didit.me/ca/management-api/sessions/batch-delete.md). Tampoc es cobreixen les transaccions: elimina-les des de 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 usuaris per `vendor_data_list`, per `didit_internal_id_list`, o per tots dos alhora; o bé
passa `delete_all: true` per eliminar tots els usuaris de l'aplicació. Els paràmetres de lot `filter_*`
de la Console es rebutgen aquí amb un `400` en lloc d'ignorar-se, perquè una intenció restringida
mai no es pugui convertir en un esborrat total.Retorna un recompte, `{"deleted": <int>}`, i no un resultat per element. Els identificadors que no coincideixen amb res s'ometen sense avisar, així que envia una llista sense duplicats si vols comparar `deleted` amb el nombre d'identificadors que has enviat.## Model de permisosLes claus d'API pertanyen a una sola aplicació.
La clau secreta principal i les claus d'accés complet poden cridar tots els endpoints `/v3/users/*` d'aquesta aplicació, inclosa `delete`.Una [clau d'API amb permisos limitats](https://docs.didit.me/ca/console/api-keys.md) necessita accés a **Persones** (`users`): lectura per als endpoints `GET`, i escriptura per crear, actualitzar, canviar l'estat i eliminar.
Crear un usuari amb `send_verification_link: true` també necessita escriptura a **Sessions**, perquè crea una sessió i n'envia l'enllaç per correu electrònic.
Una clau sense l'accés que necessita respon amb `403`.
Una clau limitada a alguns fluxos de treball o a sessions aprovades no pot accedir als endpoints `/v3/users/*`.Els rols són un concepte de la Console: el recurs de permís `users` i les seves declaracions decideixen què pot fer un membre de l'equip a la Console, i no s'avaluen per a les sol·licituds amb clau d'API.
Consulta [Rols i permisos](https://docs.didit.me/ca/console/roles-permissions.md) per a aquesta matriu.Per evitar que un servei elimini usuaris, dona-li una clau amb només lectura de **Persones**, o sense cap accés a **Persones**.## Límits de freqüència i idempotència- Tots els endpoints `/v3/users/*` estan subjectes als [límits de freqüència](https://docs.didit.me/ca/integration/rate-limiting.md) estàndard.
- `create` **no** és idempotent: si tornes a enviar la mateixa petició amb el mateix `vendor_data`, retorna un conflicte. Evita duplicats pel teu compte, o fes sempre un `GET` primer.
- `delete` és idempotent: eliminar un usuari ja eliminat no té cap efecte.## Webhooks activats per aquestes operacions| Operació | Webhook |
| - | - |
| `create` | cap per a la pròpia crida create: el primer `user.data.updated` arriba quan una sessió o una actualització omple el perfil per primera vegada |
| `update` | `user.data.updated` (amb `changed_fields`) |
| `update-status` | `user.status.updated` |
| `delete` | cap: registra l'eliminació pel teu costat si necessites reaccionar-hi |## Passos següents> [card] [Model de dades](https://docs.didit.me/ca/entities/users/data-model.md)
>
> Referència completa dels camps.> [card] [API de llistat](https://docs.didit.me/ca/management-api/users/list.md)
>
> Esquema de GET /v3/users/.> [card] [API de creació](https://docs.didit.me/ca/management-api/users/create.md)
>
> Esquema de POST /v3/users/create/.> [card] [Pujar una cara](https://docs.didit.me/ca/management-api/users/upload-face.md)
>
> Adjunta imatges facials importades als perfils d'usuari.


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