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

# Operações de utilizadores do fornecedor: CRUD

> Crie, consulte, atualize, altere o estado e elimine utilizadores do fornecedor na Didit através da Management API. Preços por utilização, sem contratos.



Prompt de operações sobre utilizadores
        Copiar o prompt para a área de transferência



      
      

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



      
      

Colar em

A gestão das entidades de utilizador principais é feita através de endpoints públicos em `/v3/users/`. Os anexos de perfil, como o carregamento de uma face importada, usam o caminho organização/aplicação com `didit_internal_id`. Esta página apresenta a visão conceptual: consulte a [referência da API](https://docs.didit.me/pt/management-api/users/list.md) para os esquemas completos de pedido / resposta.## Listar utilizadores**`GET /v3/users/`**Devolve uma lista paginada de utilizadores da sua aplicação. Suporta filtros por estado, pesquisa, intervalo de datas e outros.```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 utilização:- Sincronizar diariamente um subconjunto de utilizadores para o seu armazém de dados.
- Encontrar utilizadores sinalizados para uma fila de analistas.
- Pesquisar utilizadores pelo nome de apresentação.## Obter um utilizador**`GET /v3/users/{vendor_data}/`**Obtenha um único utilizador pelo `vendor_data`. Devolve o [modelo de dados](https://docs.didit.me/pt/entities/users/data-model.md) completo, incluindo os contadores agregados.```bash theme={null}
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
```> [!NOTE]
>
> O `vendor_data` no URL é sensível a maiúsculas e minúsculas. Envie sempre o valor exato que usou na criação da sessão.## Criar um utilizador**`POST /v3/users/create/`**Crie uma entidade de utilizador antes de executar qualquer sessão. Útil para:- Pré-carregar metadados ou campos personalizados antes de o cliente proceder à verificação.
- Definir um estado inicial (por exemplo, `FLAGGED` enquanto a sua equipa de onboarding analisa documentos manualmente).
- Carregar previamente utilizadores de uma base de dados existente, para ter uma lista completa desde o primeiro 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" }
  }'
```Se já existir um utilizador com esse `vendor_data`, a chamada devolve um erro de conflito. Nesse caso, use `PATCH` para atualizar.Também pode enviar os dados de contacto: `first_name` e `last_name` (combinados em `full_name` quando não enviar este último), `email`, `phone_number` e `country`.
A Didit guarda `email` e `phone_number` em `metadata.contact`, e `country` em `metadata.address`.Para convidar a pessoa a verificar-se na mesma chamada, adicione `send_verification_link: true` com um `email` e um `workflow_id`.
A Didit cria uma sessão de verificação para a pessoa nesse fluxo e envia-lhe a ligação por e-mail.
O `verification_link` da resposta inclui o `session_id`, o `session_number`, o `status`, o `url`, o `workflow_id` e o `email` da sessão, e é `null` quando não pede uma ligação.
Consulte [Criar utilizador](https://docs.didit.me/pt/management-api/users/create.md#enviar-uma-ligação-de-verificação) para as validações e os erros.## Carregar uma face importada**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**Associe uma imagem facial fidedigna a um perfil de utilizador existente. Este é o passo seguinte adequado quando importa utilizadores de outro fornecedor e quer que a Didit guarde as respetivas provas faciais antes da primeira sessão na 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"
  }'
```Consulte [Carregar face do utilizador](https://docs.didit.me/pt/management-api/users/upload-face.md) para os campos do pedido, os limites, os endpoints de listagem e eliminação e a distinção em relação à lista de bloqueio.## Atualizar um utilizador**`PATCH /v3/users/{vendor_data}/`**Atualize os campos de perfil editáveis. A maioria dos campos derivados de sessões verificadas é só de leitura. Tentar alterá-los através de PATCH será ignorado ou assinalado no registo de auditoria.**Campos editáveis:** `display_name`, `metadata`, `tags`.
**Só de leitura após a verificação:** `full_name`, `date_of_birth`, `portrait_image`, todos os contadores agregados, 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 um webhook `user.data.updated` com o array `changed_fields`.## Alterar o estado**`PATCH /v3/users/{vendor_data}/update-status/`**Mude um utilizador entre `ACTIVE`, `FLAGGED` e `BLOCKED`. As alterações de estado são aplicadas às sessões e transações 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 → para | Gatilho comum |
| - | - |
| `ACTIVE` → `FLAGGED` | Regra de transações, análise de um analista, alerta de monitorização AML contínua |
| `ACTIVE` → `BLOCKED` | Fraude confirmada, entrada manual na lista de bloqueio, correspondência na lista de bloqueio |
| `FLAGGED` → `ACTIVE` | Revisão concluída pelo analista |
| `BLOCKED` → `ACTIVE` | Desbloqueio manual por um analista |Emite um webhook `user.status.updated`.## Eliminar utilizadores (em lote)**`POST /v3/users/delete/`**Elimine um ou mais utilizadores. Os registos dos utilizadores são eliminados permanentemente, juntamente com todos os [templates biométricos](https://docs.didit.me/pt/management-api/biometric-templates/overview.md) retidos para eles após a eliminação das sessões. As respetivas sessões de verificação não são abrangidas por este endpoint e mantêm-se, com a ligação ao utilizador removida. Elimine-as com [Eliminar sessão](https://docs.didit.me/pt/sessions-api/delete-session.md) ou [Eliminar sessões em lote](https://docs.didit.me/pt/management-api/sessions/batch-delete.md). As transações também não são abrangidas. Elimine-as na Consola.```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"]
  }'
```Selecione os utilizadores por `vendor_data_list`, por `didit_internal_id_list` ou por ambos em simultâneo. Em alternativa, envie `delete_all: true` para remover todos os utilizadores da aplicação.
Os parâmetros de lote `filter_*` da Consola são recusados aqui com um `400`, em vez de serem ignorados, para que uma intenção restrita nunca se transforme numa eliminação total.Devolve uma contagem, `{"deleted": <int>}`, e não um resultado por item. Os identificadores sem correspondência são ignorados silenciosamente. Por isso, envie uma lista sem duplicados se quiser comparar `deleted` com o número de identificadores enviados.## Modelo de permissõesAs chaves de API pertencem a uma única aplicação.
O segredo principal e as chaves de acesso total podem chamar todos os endpoints `/v3/users/*` dessa aplicação, incluindo `delete`.Uma [chave de API com âmbito limitado](https://docs.didit.me/pt/console/api-keys.md) precisa de acesso a **Pessoas** (`users`): leitura para os endpoints `GET` e escrita para criar, atualizar, alterar o estado e eliminar.
Criar um utilizador com `send_verification_link: true` requer também escrita em **Sessões**, porque cria uma sessão e envia a respetiva ligação por e-mail.
Uma chave sem o acesso necessário responde com `403`.
Uma chave limitada a alguns fluxos ou a sessões aprovadas não consegue aceder de todo aos endpoints `/v3/users/*`.As funções são um conceito da Consola: o recurso de permissões `users` e as respetivas autorizações determinam o que um membro da equipa pode fazer na Consola, e não são avaliados nos pedidos com chave de API.
Consulte [Funções e permissões](https://docs.didit.me/pt/console/roles-permissions.md) para ver essa matriz.Para impedir que um serviço elimine utilizadores, atribua-lhe uma chave apenas com leitura em **Pessoas**, ou sem qualquer acesso a **Pessoas**.## Limites de pedidos e idempotência- Todos os endpoints `/v3/users/*` estão sujeitos aos [limites de pedidos](https://docs.didit.me/pt/integration/rate-limiting.md) padrão.
- `create` **não** é idempotente: repetir a chamada com o mesmo `vendor_data` devolve um conflito. Evite duplicados do seu lado ou faça sempre um `GET` antes.
- `delete` é idempotente: eliminar um utilizador já eliminado não tem efeito.## Webhooks disparados por estas operações| Operação | Webhook |
| - | - |
| `create` | nenhum para a própria chamada create: o primeiro `user.data.updated` chega quando uma sessão ou uma atualização preenche o perfil pela primeira vez |
| `update` | `user.data.updated` (com `changed_fields`) |
| `update-status` | `user.status.updated` |
| `delete` | nenhum: registe a eliminação do seu lado se precisar de reagir a ela |## Próximos passos> [card] [Modelo de dados](https://docs.didit.me/pt/entities/users/data-model.md)
>
> Referência completa dos campos.> [card] [API de listagem](https://docs.didit.me/pt/management-api/users/list.md)
>
> Esquema de GET /v3/users/.> [card] [API de criação](https://docs.didit.me/pt/management-api/users/create.md)
>
> Esquema de POST /v3/users/create/.> [card] [Carregar rosto](https://docs.didit.me/pt/management-api/users/upload-face.md)
>
> Anexe imagens faciais importadas aos perfis de utilizador.


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