Pular para o conteúdo principal
POST
curl
Envie uma imagem de rosto codificada em base64 para uma lista de bloqueio ou lista de permissão de rostos. A Didit detecta os rostos na imagem, mantém o maior deles, armazena a imagem e um recorte desse rosto e calcula o template biométrico facial com o qual as novas sessões são comparadas. O value da nova entrada é o UUID desse rosto. Disponível apenas para listas com entry_type: face e list_type: blocklist ou list_type: allowlist.
Se você está adicionando um rosto à lista de bloqueio ou à lista de permissão a partir de uma sessão existente, use Criar entrada com reference_session_id: assim, a entrada fica vinculada à sessão.
A imagem deve conter um rosto claramente visível e ter no máximo 2 MB depois de decodificada. Se nenhum rosto for detectado, a requisição retorna 400 e nenhuma entrada é criada. Se a análise facial estiver temporariamente indisponível, a requisição retorna 503: tente novamente mais tarde.
Para remover o rosto da lista, exclua a entrada correspondente: ela deixa de gerar correspondências com novas sessões.

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.

Parâmetros de caminho

list_uuid
string<uuid>
obrigatório

UUID de uma lista com entry_type: face e list_type: blocklist ou allowlist.

Corpo

application/json
image
string<byte>
obrigatório

JPEG ou PNG codificado em Base64, com no máximo 2 MB após a decodificação, mostrando um rosto claramente visível. Envie a string base64 pura, sem o prefixo data:image/...;base64,.

comment
string
padrão:""

Nota opcional em texto livre, como o motivo da inclusão na lista.

Resposta

A entrada de rosto foi criada.

Um valor em uma lista.

uuid
string<uuid>
obrigatório

Identificador da entrada. Use-o como entry_uuid em Excluir uma entrada da lista.

value
string
obrigatório

O valor listado: um número de telefone em E.164, um endereço de e-mail, um número de documento, um endereço IP ou intervalo CIDR, uma impressão digital de dispositivo, um endereço de carteira, uma conta bancária, um código de país ISO 3166-1 alpha-3, um vendor_data, qualquer string em uma lista key ou o UUID do rosto armazenado em uma lista de rostos. Os valores que você envia são armazenados em letras minúsculas, exceto números de telefone e códigos de país. A correspondência não diferencia maiúsculas de minúsculas.

display_label
string | null
obrigatório

Rótulo legível. A Didit o preenche para entradas obtidas de uma sessão (por exemplo, o nome do titular e o número do documento) quando você não envia nenhum.

Maximum string length: 512
comment
string
obrigatório

Nota em texto livre. String vazia quando não definida.

added_by
string | null
obrigatório

Quem adicionou a entrada: api (uma chave de API), o e-mail de um usuário do console ou console, system ou migration (entradas criadas pela Didit), ou rule (uma ação de regra de transação ou de monitoramento).

reference_session_id
string<uuid> | null
obrigatório

Sessão de verificação da qual a entrada foi obtida. null quando a entrada foi adicionada por valor.

reference_session_number
integer | null
obrigatório

Número dessa sessão no escopo da aplicação, como exibido no console.

reference_session_type
enum<string> | null
obrigatório

kyc para uma sessão de verificação de pessoa, kyb para uma sessão de verificação de empresa, null quando não há sessão.

Opções disponíveis:
kyc,
kyb,
null
reference_object_uuid
string<uuid> | null
obrigatório

O registro que a entrada representa: o registro de rosto, documento, telefone ou e-mail lido de uma sessão, o rosto criado por Enviar um rosto para uma lista ou o UUID que você enviou (por exemplo, um UUID de transação ou o didit_internal_id de um usuário).

metadata
object | null
obrigatório

Contexto adicional. Contém as chaves definidas pela Didit (listadas aqui) mescladas com qualquer metadata que você enviou ao criar a entrada, retornadas como foram armazenadas. null quando não há nenhum.

created_at
string<date-time>
obrigatório

Quando a entrada foi adicionada.

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