CRUD de usuários: operações com usuários do vendor

O gerenciamento principal da entidade User acontece por meio de endpoints públicos em /v3/users/. Anexos de perfil, como o upload de rosto importado, usam o caminho de organização/aplicação com didit_internal_id. Esta página traz a explicação conceitual. Consulte a referência da API para ver os esquemas completos de requisição e resposta.

Listar usuários

GET /v3/users/ Retorna uma lista paginada dos usuários da sua aplicação. Aceita filtros por status, busca, intervalo de datas, entre outros.

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 diariamente um subconjunto de usuários com o seu data warehouse.
Encontrar usuários sinalizados para a fila de um analista.
Buscar usuários pelo nome de exibição.

Obter um usuário

GET /v3/users/{vendor_data}/ Recupera um único usuário pelo vendor_data. Retorna o modelo de dados completo, incluindo os contadores agregados.

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

O vendor_data na URL diferencia maiúsculas de minúsculas. Sempre envie exatamente o valor que você usou na criação da sessão.

Criar um usuário

POST /v3/users/create/ Crie uma entidade User antes do início de qualquer sessão. Isso é útil para:

Preencher metadados ou campos personalizados antes que o cliente faça a verificação.
Definir um status inicial (por exemplo, FLAGGED enquanto sua equipe de onboarding revisa documentos manualmente).
Pré-carregar usuários de um banco de dados existente para ter uma lista completa desde o primeiro dia.

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 usuário com esse vendor_data, a chamada retorna um erro de conflito. Nesse caso, use PATCH para atualizar. Você também pode enviar dados de contato: first_name e last_name (unidos em full_name quando você não envia um), email, phone_number e country. A Didit armazena email e phone_number em metadata.contact, e country em metadata.address. Para convidar a pessoa a fazer a verificação 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 de verificação (workflow) e envia o link a ela por e-mail. O verification_link da resposta traz o session_id, o session_number, o status, a url, o workflow_id e o email da sessão, e é null quando você não solicita um link. Consulte Create User para ver as verificações e os erros.

Fazer upload de um rosto importado

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ Anexe uma imagem de rosto confiável a um perfil de usuário existente. Esse é o passo seguinte adequado quando você importa usuários de outro provedor e quer que a Didit mantenha a evidência facial deles antes da primeira sessão na 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"
  }'

Consulte Upload User Face para ver os campos da requisição, os limites, os endpoints de listagem e exclusão e a diferença em relação à lista de bloqueio.

Atualizar um usuário

PATCH /v3/users/{vendor_data}/ Atualize os campos editáveis do perfil. A maioria dos campos derivados de sessões verificadas é somente leitura: tentativas de alterá-los via PATCH serão ignoradas ou sinalizadas no registro de auditoria. Campos editáveis: display_name, metadata, tags. Somente leitura após a verificação: full_name, date_of_birth, portrait_image, todos os contadores agregados e o 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 um webhook user.data.updated com o array changed_fields.

Alterar o status

PATCH /v3/users/{vendor_data}/update-status/ Altere o status de um usuário entre ACTIVE, FLAGGED e BLOCKED. As alterações de status se propagam para sessões e transações 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 → para	Gatilho comum
`ACTIVE` → `FLAGGED`	Regra de transação, revisão de analista, ocorrência no monitoramento contínuo de AML
`ACTIVE` → `BLOCKED`	Fraude confirmada, sessão recusada com bloqueio automático, correspondência na lista de bloqueio
`FLAGGED` → `ACTIVE`	Analista removeu o usuário da revisão
`BLOCKED` → `ACTIVE`	Desbloqueio manual por um analista

Emite um webhook user.status.updated.

Excluir usuários (em lote)

POST /v3/users/delete/ Exclua um ou mais usuários. Os registros dos usuários são removidos permanentemente, junto com todos os templates biométricos retidos para eles após a exclusão da sessão. As sessões de verificação deles não são cobertas por este endpoint e continuam existindo, com o vínculo ao usuário removido; exclua-as com Delete Session ou Batch Delete Sessions. As transações também não são cobertas; exclua-as pelo 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"]
  }'

Selecione os usuários por vendor_data_list, por didit_internal_id_list ou pelos dois ao mesmo tempo; ou envie delete_all: true para remover todos os usuários da aplicação. Os parâmetros de lote filter_* do Console são rejeitados aqui com um 400 em vez de ignorados, para que uma intenção restrita nunca se transforme em uma exclusão total. Retorna uma contagem, {"deleted": <int>}, e não um resultado por item. Identificadores sem correspondência são ignorados silenciosamente; por isso, envie uma lista sem duplicatas se quiser comparar deleted com o número de identificadores enviados.

Modelo de permissões

As 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 escopo precisa de acesso a Pessoas (users): leitura para os endpoints GET e escrita para criar, atualizar, alterar o status e excluir. Criar um usuário com send_verification_link: true também exige escrita em Sessões, porque isso cria uma sessão e envia o link dela por e-mail. Uma chave sem o acesso necessário retorna 403. Uma chave limitada a alguns fluxos ou a sessões aprovadas não consegue acessar os endpoints /v3/users/* de forma alguma. As funções são um conceito do Console: o recurso de permissão users e suas claims definem o que um membro da equipe pode fazer no Console, e não são avaliados em requisições com chave de API. Consulte Roles & permissions para ver essa matriz. Para impedir que um serviço exclua usuários, dê a ele uma chave apenas com leitura em Pessoas, ou sem nenhum acesso a Pessoas.

Limites de requisições e idempotência

Todos os endpoints /v3/users/* estão sujeitos aos limites de requisições padrão.
create não é idempotente: tentar novamente com o mesmo vendor_data retorna um conflito. Elimine duplicatas do seu lado ou sempre faça um GET antes.
delete é idempotente: excluir um usuário já excluído não tem efeito.

Webhooks disparados por estas operações

Operação	Webhook
`create`	nenhum para a própria chamada de criação: 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: registre a exclusão do seu lado se precisar reagir a ela

Próximos passos

Modelo de dados

Referência completa dos campos.

API de listagem

Schema de GET /v3/users/.

API de criação

Schema de POST /v3/users/create/.

Enviar imagem facial

Anexe imagens de rosto importadas aos perfis de usuário.

Visão geral

Preços

Fluxos e verificação

Revisão e operações

Entidades (usuários e empresas)

Configurações e personalização

Segurança e conformidade

Didit Academy

Recursos

CRUD de usuários: operações com usuários do vendor

Listar usuários

Obter um usuário

Criar um usuário

Fazer upload de um rosto importado

Atualizar um usuário

Alterar o status

Excluir usuários (em lote)

Modelo de permissões

Limites de requisições e idempotência

Webhooks disparados por estas operações

Próximos passos

Modelo de dados

API de listagem

API de criação

Enviar imagem facial

​Listar usuários

​Obter um usuário

​Criar um usuário

​Fazer upload de um rosto importado

​Atualizar um usuário

​Alterar o status

​Excluir usuários (em lote)

​Modelo de permissões

​Limites de requisições e idempotência

​Webhooks disparados por estas operações

​Próximos passos

Modelo de dados

API de listagem

API de criação

Enviar imagem facial

Listar usuários

Obter um usuário

Criar um usuário

Fazer upload de um rosto importado

Atualizar um usuário

Alterar o status

Excluir usuários (em lote)

Modelo de permissões

Limites de requisições e idempotência

Webhooks disparados por estas operações

Próximos passos