Skip to main content
POST
cURL

Quando usar

Use este endpoint para rodar Face Match e/ou Passive Liveness sem vincular o resultado a um cliente cadastrado — útil para validar biometria antes de decidir se vale a pena criar o cadastro, ou para fluxos que não passam por POST /customers/POST /customers//documents (o par selfie+identidade não dispara a verificação automática — ver Verificação Facial para os dois fluxos lado a lado). Requer escopo biometria:write e o módulo “Verificação facial” ativo para o tenant — ativação em duas camadas (módulo no master + configuração no tenant), nenhuma acionável via esta ou qualquer outra chamada de API.

Corpo da requisição

O corpo é multipart/form-data. Formato de imagem: JPG, PNG, WEBP ou TIFF. Tamanho máximo: 5MB por imagem — acima disso, 400 image_too_large. Formato fora da lista retorna 400 invalid_image_format.

Checks disponíveis

Pedir face_match sem ref_image retorna 400 missing_ref_image.

Exemplo

Resposta parcial

A resposta nunca é tudo-ou-nada. Se os dois checks forem pedidos e só um falhar no provedor, o resultado do que teve sucesso (já cobrado) volta normalmente — só aquela entrada específica de results vira {status: "Error", message: "..."}:
A resposta só escala para 502 biometric_check_failed quando nenhum dos checks pedidos teve sucesso.

O que este endpoint não faz

  • Não vincula o resultado a um cliente — customer_id é sempre null na persistência interna; esta rota nunca cria nem atualiza um customer. Para o fluxo que vincula ao cadastro, veja Verificação Facial.
  • Não tem Idempotency-Key — reenviar a mesma chamada roda (e cobra) a verificação de novo.
  • Não dispara o webhook biometric_check.completed — a chamada é síncrona e o resultado já volta na própria resposta HTTP. Assinar esse webhook não traz nenhum evento para verificações feitas por este endpoint (o evento cobre apenas o fluxo automático de POST /customers/POST /customers/{id}/documents — ver Webhooks).

Erros

Formato completo do envelope e estratégia de retry em Tratamento de erros. Os códigos deste endpoint: missing_api_key, invalid_api_key, insufficient_scope, channel_disabled, module_disabled, invalid_multipart, missing_user_image, invalid_checks, missing_ref_image, invalid_image_format, image_too_large, billing_suspended, internal_error, biometric_check_failed.

Authorizations

x-api-key
string
header
required

API key no header x-api-key (recomendado)

Headers

x-kycert-api-version
string
Example:

"2026-06-03"

Body

multipart/form-data
user_image
file
required

Imagem de referência do rosto do titular (JPG, PNG, WEBP ou TIFF, até 5MB)

ref_image
file

Segunda imagem para comparação — obrigatória quando checks inclui face_match (mesmas regras de formato/tamanho de user_image).

checks
string

"face_match", "passive_liveness" ou "face_match,passive_liveness". Default: face_match se ref_image foi enviado, senão passive_liveness.

Example:

"face_match,passive_liveness"

Response

Verificação processada. A resposta nunca é "tudo ou nada" — quando os dois checks são pedidos e só um falha no provedor, o outro (já rodado e já cobrado) é retornado normalmente; só escala para 502 quando NENHUM check pedido teve sucesso.

object
enum<string>
Available options:
facial_verification
results
object

Chaveado pelos checks pedidos (face_match, passive_liveness). Cada entrada é {status: Approved|Declined, score, warnings, request_id} ou, se aquele check específico falhou no provedor, {status: Error, message}.

livemode
boolean