> ## 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.
# Obter usuário via API: entidade User do fornecedor
> Obtenha um User da Didit por vendor_data com campos de identidade, status, contadores de KYC e mapa de recursos. KYC persistente, pague por chamada.
Prompt para obter usuário
Copiar o prompt para a área de transferência
\
\`Goal: Fetch a single Didit User entity by your own vendor_data.
Endpoint: GET https://verification.didit.me/v3/users/{vendor_data}/
Auth header: x-api-key:
Path param:
\- vendor_data (string, REQUIRED) — your unique identifier. Free-form string, NOT a UUID. Matching is case-insensitive after Didit normalisation. URL-encode it.
curl:
curl -X GET 'https://verification.didit.me/v3/users/user-abc-123/' \
-H 'x-api-key: YOUR_API_KEY'
Response 200 (UserDetailItem) — extends the list shape with metadata, comments (activity log), and updated_at. Key fields:
\- didit_internal_id (UUID — Didit's stable internal identifier)
\- vendor_data (string)
\- display_name, full_name, date_of_birth, effective_name, portrait_image_url
\- status: "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorUserStatusChoices)
\- session_count, approved_count, declined_count, in_review_count (aggregate counters)
\- features (map of feature -> latest status)
\- approved_emails, approved_phones, issuing_states
\- metadata (arbitrary JSON you attached)
\- comments (chronological activity log: status changes, manual notes, system events)
\- created_at, updated_at
See /reference/data-models for the full schema.
Notes:
\- Aggregate counters update in real time as sessions reach terminal status.
\- For bulk lookups, prefer paging GET /v3/users/ and indexing locally on vendor_data instead of fanning out one call per identifier.
Failure modes (envelope {"detail": "..."}):
\- 401 — missing or invalid x-api-key.
\- 403 — the API key is revoked or is not valid for this application.
\- 404 — no user with that vendor_data in this application.
\- 429 — rate-limited.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
Colar em
## Visão geralRetorna uma única [entidade User](https://docs.didit.me/pt-br/entities/users/overview.md) identificada por `vendor_data`. As respostas incluem `didit_internal_id`, o identificador interno estável da Didit.## Quando usar- **Consulta** do estado de verificação atual de um usuário: o mapa `features` traz o status mais recente de cada recurso em um único objeto.
- **Telas de detalhes** na sua própria interface: busque o perfil sob demanda antes de renderizar.
- **Pontuação de risco**: combine os contadores de sessões e `features` para pontuar cada usuário do seu lado.## Observações- `vendor_data` na URL diferencia maiúsculas de minúsculas.
- Retorna `404` se não existir nenhum usuário com esse `vendor_data` na aplicação.
- Os contadores agregados (`session_count`, `approved_count`, `declined_count`, `in_review_count`) são atualizados em tempo real à medida que as sessões são concluídas.
- Consulte o [modelo de dados do usuário](https://docs.didit.me/pt-br/entities/users/data-model.md) para ver todos os campos.## PermissõesQualquer chave de API ativa da aplicação pode chamar este endpoint. As chaves de API da Didit são
**vinculadas à aplicação, não à função**: as [funções e permissões](https://docs.didit.me/pt-br/console/roles-permissions.md) do Console
(`read:users` e as demais) definem o que uma *pessoa* pode fazer no Console e não são avaliadas
no tráfego da Management API. Controle quem pode chamar este endpoint controlando quem tem acesso
à chave de API da aplicação.## Relacionados- [Visão geral de usuários](https://docs.didit.me/pt-br/entities/users/overview.md)
- [Modelo de dados](https://docs.didit.me/pt-br/entities/users/data-model.md)
- [Listar usuários](https://docs.didit.me/pt-br/management-api/users/list.md)
## OpenAPI
````yaml pt-br/openapi-25.json GET /v3/users/{vendor_data}/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/users/{vendor_data}/:
get:
tags:
- Users
summary: Obter usuário
description: >-
Busca um [usuário](/entities/users) por `vendor_data` (correspondência
exata). Acrescenta `metadata`, `comments` e `updated_at` à visualização
da lista e muda `tags` para o formato detalhado de vínculo de tags.
operationId: get_user
parameters:
- name: vendor_data
in: path
required: true
schema:
type: string
description: >-
Seu identificador exclusivo do usuário: uma string livre (NÃO um
UUID). É o mesmo valor que você passou como `vendor_data` ao criar a
sessão que introduziu esse usuário pela primeira vez, comparado
exatamente como enviado.
example: user-abc-123
responses:
'200':
description: >-
Detalhes completos do usuário, incluindo metadados,
comentários/registro de atividades e dados agregados das sessões.
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetailItem'
examples:
Active user:
value:
didit_internal_id: f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418
vendor_data: user-abc-123
display_name: null
full_name: John Michael Doe
date_of_birth: '1990-05-15'
effective_name: John Michael Doe
status: ACTIVE
metadata:
tier: premium
source: website
portrait_image_url: https:///...
session_count: 3
approved_count: 2
declined_count: 0
in_review_count: 1
issuing_states:
- USA
approved_emails:
- john@example.com
approved_phones:
- '+14155551234'
features:
ID_VERIFICATION: Approved
LIVENESS: Approved
FACE_MATCH: Approved
AML: Approved
features_list:
- feature: ID_VERIFICATION
status: Approved
- feature: LIVENESS
status: Approved
- feature: FACE_MATCH
status: Approved
- feature: AML
status: Approved
last_session_at: '2025-06-15T10:30:00Z'
last_activity_at: '2025-06-15T10:30:00Z'
first_session_at: '2025-06-01T08:00:00Z'
tags:
- uuid: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
tag:
uuid: e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b
name: VIP
color: '#2567FF'
description: null
source: custom
created_at: '2025-05-01T09:00:00Z'
updated_at: '2025-05-01T09:00:00Z'
added_by_email: analyst@acme.com
added_by_name: Jane Analyst
created_at: '2025-06-02T11:00:00Z'
comments:
- uuid: c1111111-2222-4333-8444-555555555555
comment_type: STATUS_CHANGED
comment: null
actor_email: analyst@acme.com
actor_name: Jane Analyst
previous_status: FLAGGED
new_status: ACTIVE
previous_value: null
new_value: null
changed_fields: []
metadata: null
mentioned_emails: []
created_at: '2025-06-01T10:30:00Z'
created_at: '2025-06-01T08:00:00Z'
updated_at: '2025-06-15T10:30:00Z'
'401':
description: >-
Nenhuma credencial fornecida. Requisições para caminhos
`/v3/users/*` sem um cabeçalho `x-api-key` (ou token `Authorization:
Bearer`) são rejeitadas pelo middleware de autenticação antes de
chegarem à API.
content:
application/json:
examples:
Missing credentials:
value:
detail: >-
You must be authenticated with a valid access token to
access this endpoint.
'403':
description: >-
Chave de API inválida ou revogada, ou a chave não pode ler os
usuários desta aplicação. Uma chave ausente retorna `403`; uma chave
incorreta, revogada ou expirada retorna `401`.
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'404':
description: >-
Não existe nenhum usuário com o `vendor_data` informado nesta
aplicação.
content:
application/json:
examples:
Not found:
value:
detail: Not found.
'429':
description: >-
Limite de requisições excedido; aguarde e tente novamente após o
intervalo indicado em `Retry-After`.
content:
application/json:
examples:
Rate limited:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
curl -X GET 'https://verification.didit.me/v3/users/user-abc-123/' \
-H 'x-api-key: YOUR_API_KEY'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.users.retrieve(
"user-abc-123",
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.users.retrieve("user-abc-123");
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Retrieve(ctx, \"user-abc-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: |-
import me.didit.Didit;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.users().retrieve("user-abc-123");
System.out.println(result);
- lang: php
label: PHP
source: |-
users->retrieve('user-abc-123');
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.users.retrieve("user-abc-123")
puts result.to_h
- lang: csharp
label: .NET
source: |-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Users.RetrieveAsync("user-abc-123");
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
UserDetailItem:
type: object
description: >-
Detalhes completos do usuário. Estende UserListItem com metadados,
comentários e updated_at.
allOf:
- $ref: '#/components/schemas/UserListItem'
- type: object
properties:
metadata:
type: object
description: >-
JSON de metadados personalizados que você anexou a este usuário.
O padrão é `{}`.
tags:
type: array
description: >-
Atribuições de tags. OBSERVAÇÃO: nas respostas de detalhe, cada
entrada é um objeto de *vínculo* de tag (`{uuid, tag: {...},
added_by_email, added_by_name, created_at}`), diferente do
formato plano `{uuid, name, color}` usado nas respostas de
lista.
items:
type: object
properties:
uuid:
type: string
format: uuid
description: UUID da atribuição da tag (não da tag em si).
tag:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description:
type: string
nullable: true
source:
type: string
enum:
- didit
- custom
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
added_by_email:
type: string
nullable: true
added_by_name:
type: string
nullable: true
created_at:
type: string
format: date-time
comments:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
comment_type:
type: string
enum:
- COMMENT
- STATUS_CHANGED
- METADATA_UPDATED
- TAG_ADDED
- TAG_REMOVED
- PROFILE_UPDATED
comment:
type: string
nullable: true
actor_email:
type: string
nullable: true
actor_name:
type: string
nullable: true
previous_status:
type: string
nullable: true
enum:
- ACTIVE
- FLAGGED
- BLOCKED
- null
new_status:
type: string
nullable: true
enum:
- ACTIVE
- FLAGGED
- BLOCKED
- null
previous_value:
type: object
nullable: true
description: >-
Valores anteriores dos campos para entradas
PROFILE_UPDATED.
new_value:
type: object
nullable: true
description: Novos valores de campo para entradas PROFILE_UPDATED.
changed_fields:
type: array
items:
type: string
description: >-
Nomes dos campos alterados por uma entrada
PROFILE_UPDATED.
metadata:
type: object
nullable: true
mentioned_emails:
type: array
items:
type: string
created_at:
type: string
format: date-time
description: >-
Registro de atividades e comentários deste usuário (alterações
de status, edições de perfil, notas manuais).
updated_at:
type: string
format: date-time
UserListItem:
type: object
description: Um usuário verificado.
properties:
didit_internal_id:
type: string
format: uuid
description: UUID interno estável da Didit para este usuário.
vendor_data:
type: string
nullable: true
description: >-
Seu identificador exclusivo deste usuário (passado ao criar
sessões). Pode ser nulo quando nenhum identificador do fornecedor
foi informado.
display_name:
type: string
nullable: true
description: Nome de exibição personalizado definido por você
full_name:
type: string
nullable: true
description: Nome completo extraído dos documentos verificados
date_of_birth:
type: string
format: date
nullable: true
effective_name:
type: string
nullable: true
description: >-
Melhor nome disponível: display_name, se definido; caso contrário,
full_name
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
description: >-
Status do ciclo de vida do registro do usuário (NÃO é um status de
sessão). `ACTIVE` é o padrão, `FLAGGED` marca o usuário para atenção
manual e `BLOCKED` impede novas sessões para este `vendor_data`.
portrait_image_url:
type: string
nullable: true
description: >-
URL pré-assinada da foto de retrato do usuário (expira após algumas
horas)
session_count:
type: integer
description: Número total de sessões de verificação deste usuário
approved_count:
type: integer
description: Número de sessões aprovadas
declined_count:
type: integer
description: Número de sessões recusadas
in_review_count:
type: integer
description: Número de sessões em revisão
issuing_states:
type: array
items:
type: string
description: >-
Códigos ISO 3166-1 alpha-3 dos países emissores encontrados nos
documentos de identidade aprovados deste usuário, por exemplo,
`["USA", "ESP"]`. Array vazio quando não houver nenhum.
approved_emails:
type: array
items:
type: string
description: >-
Endereços de e-mail verificados coletados das sessões aprovadas
deste usuário, por exemplo, `["john@example.com"]`.
approved_phones:
type: array
items:
type: string
description: >-
Números de telefone verificados coletados das sessões aprovadas
deste usuário, por exemplo, `["+14155551234"]`.
features:
type: object
description: >-
Status agregado por recurso em todas as sessões deste usuário.
Chaves possíveis: `ID_VERIFICATION`, `NFC`, `LIVENESS`,
`FACE_MATCH`, `POA`, `QUESTIONNAIRE`, `EMAIL_VERIFICATION`, `PHONE`,
`AML`, `IP_ANALYSIS`, `AGE_ESTIMATION`, `DATABASE_VALIDATION`.
Valores possíveis: `Approved`, `Declined`, `In Review`, `Not
Finished`, `Resub Requested`.
features_list:
type: array
items:
type: object
properties:
feature:
type: string
status:
type: string
description: >-
Os mesmos dados de `features`, como um array ordenado de objetos
`{feature, status}`.
last_session_at:
type: string
format: date-time
nullable: true
description: Data e hora da sessão mais recente
first_session_at:
type: string
format: date-time
nullable: true
description: Data e hora da primeira sessão
last_activity_at:
type: string
format: date-time
nullable: true
description: >-
Data e hora da atividade mais recente deste usuário (sessão,
transação, mudança de status, edição de dados etc.).
tags:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description: Tags atribuídas a este usuário
created_at:
type: string
format: date-time
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Chave de API da sua aplicação, em Developers -> API keys no Business
Console. A chave principal tem acesso total. Uma chave nomeada pode ter
escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada
a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a
uma data de validade. 401 significa que a chave está errada, revogada ou
expirada; 403 significa que nenhuma chave foi enviada, que a chave não
tem acesso a este recurso ou ação, ou que a requisição veio de um
endereço fora da sua lista de IPs; 404 em uma rota de sessão significa
que a sessão está fora dos fluxos ou status da chave. Uma chave sem
acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave
sem permissão de escrita em sessões recebe links e tokens de sessão como
null. Consulte https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.