Skip to main content
POST
/
api
/
kyc
/
id-verification
ID Verification (Frente/Verso do documento)
curl --request POST \
  --url http://api.gu1.ai/api/kyc/id-verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentFront": {},
  "documentBack": {},
  "entityId": "<string>",
  "vendorData": "<string>",
  "performDocumentLiveness": true,
  "minimumAge": 123,
  "expirationDateNotDetectedAction": "<string>",
  "invalidMrzAction": "<string>",
  "inconsistentDataAction": "<string>"
}
'

​
Resumo

ID Verification é um serviço de verificação da Gueno que valida um documento de identidade enviando a imagem da frente (obrigatória) e opcionalmente a imagem do verso (para documentos de duas faces como RG). A API retorna Aprovado ou Recusado, dados extraídos (nome, número do documento, data de nascimento, endereço, MRZ, etc.) e avisos opcionais. Não há sessão hospedada: você envia as imagens e recebe o resultado em uma chamada.
Quando usar cada um
  • KYC por sessão (POST /api/kyc/validations): Fluxo completo com URL hospedada, selfie ao vivo e captura de documento.
  • Face Match (POST /api/kyc/face-match): Comparar foto do documento e selfie; retorna correspondência + pontuação.
  • ID Verification (POST /api/kyc/id-verification): Enviar frente (e opcional verso) do documento; obter validação, dados extraídos e Aprovado/Recusado. Ideal quando você já tem as imagens do documento.

​
Pré-requisitos

  1. Integração ID Verification ativada na organização.
  2. API key configurada nas configurações KYC da organização.

​
Solicitação

​
Endpoint

POST https://api.gu1.ai/api/kyc/id-verification

​
Content-Type

Apenas multipart/form-data é aceito. Você pode enviar as imagens de duas formas:
  1. Como arquivos: anexar nos campos documentFront e (opcional) documentBack.
  2. Como base64: enviar os mesmos nomes de campo com a imagem em base64.
documentFront é obrigatório: é preciso enviar arquivo ou base64. Se não enviar nenhum, a API retorna 400. documentBack é opcional. Se enviar arquivo e base64 para o mesmo campo, o arquivo é usado.

​
Headers

Authorization: Bearer SUA_API_KEY
Content-Type: multipart/form-data; boundary=----...
Incluir X-Organization-Id se a conta usa organização.

​
Campos do form

​
documentFront
file | string
required
Imagem da frente do documento. Enviar como arquivo ou como string (base64). Formatos: JPEG, PNG, WebP, TIFF, PDF. Máx. 5MB.
​
documentBack
file | string
Imagem do verso (opcional). Mesmo formato que documentFront.
​
entityId
string
UUID opcional da entidade pessoa. Para auditoria e listagem por entidade.
​
vendorData
string
Referência opcional para rastreamento.
​
performDocumentLiveness
boolean
Realizar liveness do documento (detectar tela/cópia). Padrão false. Enviar como string no form.
​
minimumAge
number
Idade mínima (1–120); abaixo disso é recusado. Opcional.
​
expirationDateNotDetectedAction
string
"NO_ACTION" ou "DECLINE" quando a data de validade não é detectada. Opcional.
​
invalidMrzAction
string
"NO_ACTION" ou "DECLINE" quando o MRZ é inválido. Opcional.
​
inconsistentDataAction
string
"NO_ACTION" ou "DECLINE" quando os dados visuais não batem com o MRZ. Opcional.

​
Resposta (200 OK)

CampoTipoDescrição
statusstring"approved" | "declined".
verificationIdstring (opcional)ID do registro de auditoria.
requestIdstring (opcional)ID interno da solicitação.
extractedDataobject (opcional)Dados extraídos: nome, número do documento, data de nascimento, etc.
warningsstring[] (opcional)Array de códigos de risco (ex.: DOCUMENT_EXPIRED, POSSIBLE_DUPLICATED_USER). Veja Códigos de risco em avisos para todos os valores.

​
Exemplo de solicitação

const form = new FormData();
form.append('documentFront', documentFrontFile);
if (documentBackFile) form.append('documentBack', documentBackFile);
form.append('entityId', '123e4567-e89b-12d3-a456-426614174000');

const response = await fetch('https://api.gu1.ai/api/kyc/id-verification', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer SUA_API_KEY' },
  body: form,
});
const result = await response.json();

​
Erros

CódigoHTTPSignificado
NOT_CONFIGURED403API key não configurada na organização.
NOT_ENABLED403Integração ID Verification não ativada.
INVALID_REQUEST400Content-Type não é multipart/form-data ou frente faltando/inválido (sem arquivo nem base64).
VERIFICATION_FAILED500Falha genérica; tentar novamente ou outro documento.

​
Auditoria e listagem de verificações

Cada solicitação de ID Verification é armazenada em id_verification_verifications. A resposta do POST inclui verificationId quando persistido. Todos os endpoints são da API Gueno; nesta documentação e nas respostas não é mencionado nenhum provedor externo.

​
Obter uma verificação

GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id
Retorna um registro por ID. Path: id — UUID da verificação (o verificationId da resposta do POST ou da listagem). Resposta (200): Mesmo formato de um item da listagem. 404 se não existir ou não pertencer à sua organização.

​
Listar verificações

GET https://api.gu1.ai/api/kyc/id-verification/verifications?entityId={entityId}&limit=50&offset=0
Query: entityId (opcional), withoutEntity (boolean), status, limit, offset. Resposta: { "verifications": [ ... ], "pagination": { ... } }.

​
Obter imagens do documento armazenadas

Se a verificação tiver imagens armazenadas, você pode obtê-las com: 
GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id/document-front-image
GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id/document-back-image
Path: id — UUID da verificação. Resposta: bytes da imagem. 404 se não existir ou não houver imagem armazenada para esse lado.

​
Próximos passos

Face Match (Documento + Selfie)

Comparar documento e selfie

Criar validação KYC

Verificação por sessão com URL hospedada