Pular para o conteúdo principal
POST
cURL

Autorizações

x-api-key
string
header
obrigatório

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.

Corpo

multipart/form-data
user_image
file
obrigatório

Imagem de rosto ao vivo ou candidata a verificar (por exemplo, uma selfie). Envie uma única foto frontal com o rosto da pessoa claramente visível e bem iluminado. Extensões permitidas: tiff, jpg, jpeg, png, webp. Tamanho máximo de upload: 5 MB (arquivos maiores são rejeitados com 400). As imagens são compactadas automaticamente para cerca de 0,5 MB antes do processamento, portanto resoluções muito altas não melhoram a precisão.

ref_image
file
obrigatório

Imagem facial de referência para comparação (por exemplo, o retrato de um documento de identidade ou uma foto cadastrada anteriormente). Mesmos limites de formato e tamanho de user_image.

face_match_score_decline_threshold
number<float>
padrão:30

Limiar de similaridade (0–100) que determina o status da resposta. Uma pontuação calculada igual ou inferior a esse valor define status como Declined e adiciona um aviso LOW_FACE_MATCH_SIMILARITY; uma pontuação estritamente superior retorna Approved. O padrão 30 é permissivo: aumente-o (por exemplo, 50–60) para uma verificação mais rigorosa. Valores fora de 0–100 retornam 400.

Intervalo obrigatório: 0 <= x <= 100
Exemplo:

50

rotate_image
boolean
padrão:false

Quando true, o serviço testa as imagens de entrada em incrementos de 90 graus (0, 90, 180, 270) e usa a orientação que produz a melhor detecção de rosto, o que é útil para capturas móveis sem orientação EXIF. Aumenta a latência, então ative apenas se você não puder garantir imagens na posição vertical.

Exemplo:

false

save_api_request
boolean
padrão:true

Quando true (padrão), persiste a chamada como uma sessão do tipo API: visível no Business Console, recuperável via GET /v3/session/{sessionId}/decision/ usando o request_id retornado e anunciada por meio de um webhook status.updated. Quando false, nada é armazenado e request_id é um UUID transitório usado apenas para correlacionar a resposta.

Exemplo:

true

vendor_data
string

String opaca opcional (seu ID interno de usuário, e-mail, UUID…) armazenada na sessão persistida e devolvida na resposta. Use-a para correlacionar chamadas de API com seus próprios registros e para filtrar sessões posteriormente.

Exemplo:

"user-123"

metadata
object

Objeto JSON opcional armazenado com a sessão (quando save_api_request=true) e devolvido na resposta. Em requisições multipart, envie-o como um campo de string codificada em JSON (por exemplo, metadata={"flow":"login"}), que é convertido em um objeto.

Exemplo:

Resposta

Correspondência facial calculada. face_match.score é um float de 0 a 100 (duas casas decimais); status é Approved quando a pontuação está estritamente acima de face_match_score_decline_threshold e, caso contrário, Declined com um aviso explicativo. Uma similaridade baixa ou um par que não pode ser pontuado ainda retorna 200: verifique face_match.status e face_match.warnings, não apenas o código HTTP. Quando save_api_request=true, request_id é o ID da sessão persistida.

request_id
string<uuid>

ID da sessão persistida quando save_api_request=true (utilizável com GET /v3/session/{sessionId}/decision/); caso contrário, um UUID de correlação transitório.

face_match
object
vendor_data
string | null

Eco do vendor_data que você enviou, ou null.

metadata
object | null

Eco do objeto metadata que você enviou, ou null.

created_at
string<date-time>

Timestamp ISO 8601 (UTC) do momento em que a resposta foi gerada, por exemplo 2026-06-12T01:04:42.763237+00:00.

Última modificação em 1 de novembro de 2026