Saltar para o conteúdo principal
POST
cURL

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

multipart/form-data
user_image
file
obrigatório

Imagem facial frontal para efetuar a pesquisa. Extensões permitidas: tiff, jpg, jpeg, png, webp. Tamanho máximo de carregamento: 5 MB (ficheiros maiores são rejeitados com 400). As imagens são comprimidas automaticamente para ~0.5 MB antes do processamento, pelo que resoluções muito altas não melhoram a precisão. A imagem deve conter pelo menos um rosto detetável — caso contrário, o endpoint devolve 400. Quando vários rostos estão presentes, o maior é pesquisado e um aviso MULTIPLE_FACES_DETECTED é adicionado.

search_type
enum<string>
padrão:most_similar

Política de pesquisa. most_similar (predefinição) classifica cada rosto registado na sua aplicação por similaridade. blocklisted_or_approved restringe os candidatos a rostos em lista de bloqueio, rostos em lista de permissões, rostos de sessões aprovadas e rostos importados de perfis de utilizador — com as entradas na lista de bloqueio classificadas primeiro.

Opções disponíveis:
most_similar,
blocklisted_or_approved
Exemplo:

"most_similar"

rotate_image
boolean
padrão:false

Quando true, o serviço tenta rotações de 90 graus da entrada e utiliza a orientação que produzir a melhor deteção facial. Útil quando a orientação EXIF está ausente. Adiciona latência.

Exemplo:

false

save_api_request
boolean
padrão:true

Quando true (padrão), persiste a chamada como uma sessão do tipo API, emite um webhook status.updated, pré-assina os valores de match_image_url e regista o rosto pesquisado no seu índice de Pesquisa facial (os registos de Pesquisa facial são excluídos de pesquisas futuras). Quando false, a pesquisa é de execução única — nenhuma sessão é armazenada e o rosto não é registado.

Exemplo:

true

vendor_data
string

Identificador opaco opcional (o seu ID de utilizador, e-mail, UUID...) guardado na sessão persistida e devolvido. Não exclui rostos do mesmo utilizador dos resultados de pesquisa.

Exemplo:

"user-123"

metadata
object

Objeto JSON opcional armazenado com a sessão (quando save_api_request=true) e devolvido. Em pedidos multipart, envie-o como um campo de texto codificado em JSON — é convertido num objeto.

Exemplo:

Resposta

Pesquisa facial concluída. face_search.matches contém até 5 rostos semelhantes ordenados por semelhança; uma matriz vazia significa que nenhum rosto registado excedeu o limiar mínimo de semelhança. status é Declined apenas em correspondências na lista de bloqueio — correspondências duplicadas por si só devolvem Approved, portanto inspecione matches e warnings, não apenas status. Quando save_api_request=true, request_id é o id de sessão persistido. Cada correspondência contém source (session, imported, list_entry ou retained_template), vendor_user_id e biometric_template_id; uma correspondência retained_template provém de um template biométrico sem imagem mantido após a sessão de origem ter sido eliminada e tem os campos de sessão, match_image_url e user_details como null.

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.

vendor_data
string | null

Eco do vendor_data que enviou, ou null.

metadata
object | null

Eco do objeto metadata que enviou, ou null.

created_at
string<date-time>

Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada, por exemplo 2026-06-12T01:04:42.763237+00:00.

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