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>",
  "doubleCheckRenaper": true,
  "performDocumentLiveness": true,
  "minimumAge": 123,
  "expirationDateNotDetectedAction": "<string>",
  "invalidMrzAction": "<string>",
  "inconsistentDataAction": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Resumo

ID Verification é um serviço de verificação da Gu1 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, liveness e captura de documento. Ideal para onboarding e fluxos regulados.
  • Face Match (POST /api/kyc/face-match): Comparar duas imagens (foto do documento + selfie) para verificar se são a mesma pessoa; retorna correspondência + pontuação.
  • ID Verification (POST /api/kyc/id-verification): Enviar frente (e opcional verso) do documento; obter validação do documento, dados extraídos (MRZ, nome, endereço, etc.) e Aprovado/Recusado. Ideal quando você já tem as imagens do documento e só precisa de extração + validação.

​
Pré-requisitos

Antes de usar o ID Verification:
  1. Integração ID Verification ativada: Sua organização deve ter a integração KYC ID Verification ativada (por exemplo no Marketplace / Integrações).
  2. Credenciais configuradas: A API key da integração ID Verification deve estar configurada nas configurações KYC da organização (definido pelo administrador da Gu1). Apenas a API key é necessária (sem webhook secret para este endpoint).
ID Verification é um serviço da Gu1. Toda a verificação é feita na infraestrutura da Gu1.

​
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 (ou misturar):
  1. Como arquivos: anexar imagens nos campos do form documentFront e (opcional) documentBack.
  2. Como base64: enviar os mesmos nomes de campo com a imagem em base64 (com ou sem prefixo data:image/...;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=----...
Não defina Content-Type manualmente ao usar FormData; o cliente define com o boundary correto. Se sua conta usa escopo por organização, inclua: 
X-Organization-Id: SEU_ORGANIZATION_ID

​
Campos do form

​
documentFront
file | string
required
Imagem da frente do documento. Enviar como arquivo (recomendado) ou como string (base64, com ou sem prefixo data:image/...;base64,). Formatos: JPEG, PNG, WebP, TIFF, PDF. Máx. 5MB.
​
documentBack
file | string
Imagem do verso (opcional; obrigatória para documentos de duas faces como RG). Igual a documentFront: arquivo ou base64.
​
entityId
string
UUID opcional da entidade pessoa a associar a esta verificação. Usado para auditoria e para listar verificações por entidade.
​
vendorData
string
Referência opcional (por exemplo seu ID de usuário) para rastreamento. Armazenada no registro de auditoria.
​
doubleCheckRenaper
boolean
Com true, após approved do documento executa chequeo RENAPER de dados (DNI + gênero + trâmite do OCR vs renaper/data). Requer credenciais RENAPER. Query prevalece sobre o body.
​
doubleCheckRenaper
boolean
Igual ao query param doubleCheckRenaper.
​
performDocumentLiveness
boolean
Se realizar liveness do documento (detectar tela/cópia). Padrão false. Enviar como string "true" ou "false" no form.
​
minimumAge
number
Idade mínima (1–120); abaixo disso é recusado. Opcional. Enviar como string no form.
​
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

​
Resposta de sucesso (200 OK)

CampoTipoDescrição
statusstring"approved" | "declined".
verificationIdstring (opcional)ID do registro de auditoria em id_verification_verifications (suporte e listagem).
requestIdstring (opcional)ID interno da solicitação (suporte).
extractedDataobject (opcional)OCR e metadados de verificação do serviço ID Verification da Gu1, normalizados e persistidos na auditoria. Ver campos de extractedData abaixo.
warningsstring[] (opcional)Array de códigos de risco da verificação (ex.: DOCUMENT_EXPIRED, POSSIBLE_DUPLICATED_USER). Usar para exibição ou i18n. Veja Códigos de risco em avisos para todos os valores.
debugProviderResponseobject (opcional)Apenas não produção (API Gu1 com NODE_ENV=development). Resposta completa de verificação sanitizada para depuração (sem imagens/base64). Não usar em integrações de produção.
doubleCheckRenaperboolean (opcional)true se dupla verificação RENAPER foi solicitada.
responseDoubleChecksobject (opcional)Com doubleCheckRenaper=true: renaper com resultado dados/trâmite. Ver KYC validations RENAPER.
Se RENAPER falhar após aprovação OCR, status vira "declined" e códigos RENAPER entram em warnings.

​
Campos de extractedData

Os seguintes campos são devolvidos em extractedData e gravados em id_verification_verifications.extracted_data (listar/obter auditoria). Campos vazios são omitidos. Identidade e documento (comuns):
CampoTipoDescrição
providerStatusstringDetalhe do estado da verificação do documento (ex.: Approved, Declined). O status de nível superior é approved / declined.
fullName, firstName, lastNamestringNome via OCR.
firstSurname, secondSurnamestringQuando vêm em campos complementares (ex.: alguns documentos LATAM).
documentNumber, personalNumberstringNúmero do documento e número pessoal/nacional se aplicável.
documentTypestringex.: Driver's License, BI.
taxNumberstringID fiscal se aplicável (ex.: CPF em extração complementar).
dateOfBirth, agestring / numberData de nascimento e idade calculada.
expirationDate, dateOfIssue, firstIssueDatestringDatas do documento (ISO YYYY-MM-DD quando aplicável).
nationality, genderstringPaís e género quando o OCR devolve.
placeOfBirth, maritalStatusstringLocal de nascimento e estado civil se aplicável.
address, formattedAddressstringMorada quando presente.
issuingState, issuingStateNamestringJurisdição emissora (ex.: BRA, Brazil).
Complementares (aninhados; podem estar vazios):
CampoTipoDescrição
extraFieldsobjectChaves do documento não promovidas a campos de primeiro nível (ex.: categoria da carta, códigos regionais). Ponto de extensão para campos futuros do OCR.
warningMetaobjectMetadados de avisos: duplicatedSessionId, duplicatedSessionNumber, duplicatedApiService com POSSIBLE_DUPLICATED_USER.
frontImageQualityScore, backImageQualityScoreobjectPontuações de qualidade OCR quando existem.
mrzobjectCampos MRZ parseados se não vazios.
parsedAddressobjectMorada estruturada quando a verificação a devolve.
barcodesarrayLeituras de códigos de barras se aplicável.
Campos promovidos vs. extensão
  • Identificadores frequentes (taxNumber, firstSurname, secondSurname, firstIssueDate, etc.) são elevados ao mesmo nível que fullName em extractedData quando o OCR os devolve.
  • Outras chaves do documento ficam em extractedData.extraFields (mesmo objeto no POST e na listagem/detalhe de auditoria).
Não incluído nas respostas API nem no JSON de auditoria
  • URLs temporárias de imagens do fluxo de verificação — usar imagens armazenadas (document-front-image / document-back-image) do que enviou à Gu1.
  • Corpo bruto completo da verificação (não exposto em APIs de produção).
Exemplo (aprovado): 
{
  "status": "approved",
  "verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "requestId": "req_abc",
  "extractedData": {
    "providerStatus": "Approved",
    "fullName": "Elena Martínez Sánchez",
    "firstName": "Elena",
    "lastName": "Martínez Sánchez",
    "documentNumber": "YZA123456",
    "documentType": "National ID",
    "dateOfBirth": "1985-03-15",
    "expirationDate": "2030-08-21",
    "nationality": "ESP",
    "address": "Calle Mayor 10, 4B, Madrid",
    "issuingState": "ESP",
    "issuingStateName": "Spain",
    "personalNumber": "AAA123456",
    "dateOfIssue": "2020-01-10",
    "gender": "F",
    "parsedAddress": {
      "street": "Calle Mayor",
      "city": "Madrid",
      "country": "ESP",
      "formatted_address": "Calle Mayor 10, 4B, Madrid"
    },
    "frontImageQualityScore": {
      "overall_score": 97.5,
      "focus_score": 100,
      "is_document_fully_visible": true
    },
    "backImageQualityScore": {
      "overall_score": 96.0,
      "focus_score": 99
    }
  },
  "warnings": []
}
Exemplo (recusado com avisos e campos extra LATAM): 
{
  "status": "declined",
  "verificationId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "requestId": "4e2bf9fb-d75b-4b26-9362-e51436cfe1eb",
  "extractedData": {
    "providerStatus": "Declined",
    "fullName": "Breno Henrique Ferreira Silva",
    "firstName": "Breno Henrique",
    "lastName": "Ferreira Silva",
    "firstSurname": "Ferreira",
    "secondSurname": "Silva",
    "documentNumber": "08585626509",
    "personalNumber": "2156732124SSPBA",
    "documentType": "Driver's License",
    "taxNumber": "10584158599",
    "dateOfBirth": "2004-08-29",
    "age": 21,
    "expirationDate": "2025-03-07",
    "dateOfIssue": "2024-03-08",
    "firstIssueDate": "2024-03-08",
    "nationality": "BRA",
    "gender": "U",
    "placeOfBirth": "Barreiras/Ba",
    "maritalStatus": "UNKNOWN",
    "issuingState": "BRA",
    "issuingStateName": "Brazil",
    "warningMeta": {
      "duplicatedSessionId": "a4bfeef8-6d6e-4e9b-8fcb-44950912b2b4",
      "duplicatedSessionNumber": 2834,
      "duplicatedApiService": "ID_VERIFICATION"
    },
    "frontImageQualityScore": {
      "overall_score": 98.2,
      "focus_score": 100,
      "brightness_score": 94,
      "is_document_fully_visible": true
    },
    "formattedAddress": null,
    "extraFields": {
      "license_category": "AB",
      "restrictions": "01"
    },
    "mrz": {
      "line1": "IDBRA085856265<<<<<<<<<<<<<<<",
      "line2": "0408299M2503077BRA<<<<<<<<<<<6",
      "line3": "SILVA<<BRENO<HENRIQUE<FERREIRA"
    },
    "parsedAddress": {},
    "backImageQualityScore": {
      "overall_score": 97.1,
      "focus_score": 100
    },
    "barcodes": []
  },
  "warnings": ["DOCUMENT_EXPIRED", "POSSIBLE_DUPLICATED_USER"]
}

​
Exemplo de solicitação

const form = new FormData();
form.append('documentFront', documentFrontFile); // File object
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();
console.log('Status:', result.status, 'Data:', result.extractedData);

​
Respostas de erro

Códigos de erro comuns:
CódigoHTTPSignificado
NOT_CONFIGURED403Credenciais do ID Verification (API key) não configuradas na organização.
NOT_ENABLED403Integração ID Verification não ativada para esta organização.
INVALID_REQUEST400Content-Type não é multipart/form-data, ou frente do documento faltando/inválida (sem arquivo nem base64, ou formato/tamanho).
FORBIDDEN403Não foi possível concluir a verificação (ex.: créditos).
VERIFICATION_FAILED500Não foi possível concluir a verificação; tentar novamente ou outro documento.

​
Auditoria e listagem de verificações

Cada solicitação de ID Verification (sucesso ou falha) é armazenada em id_verification_verifications para auditoria e conformidade. A resposta inclui verificationId (ID do registro de auditoria) quando a persistência tem sucesso. Todos os endpoints abaixo são da API Gu1.

​
Obter uma verificação

GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id
Retorna um registro de auditoria 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: id, organizationId, entityId, status, requestId, vendorData, errorMessage, warnings, extractedData, createdAt, documentFrontStoragePath, documentBackStoragePath, storageProvider, etc.
404 se não existir ou não pertencer à sua organização.

​
Listar registros de auditoria

GET https://api.gu1.ai/api/kyc/id-verification/verifications?entityId={entityId}&limit=50&offset=0
Parâmetros de query:
ParâmetroTipoDescrição
entityIdstring (UUID)Opcional. Filtrar por entidade pessoa.
withoutEntitybooleanSe true, retorna apenas verificações sem entidade associada (ex.: aba «ID Verification sem entidade» no KYC).
statusstringOpcional. Filtrar por status (approved, declined, failed).
limitnumberMáximo de itens (padrão 50, máx. 100).
offsetnumberDeslocamento da paginação.
Resposta: { "verifications": [ ... ], "pagination": { "limit", "offset", "total" } }. Cada verificação inclui id, entityId, status, requestId, extractedData, warnings, errorMessage, createdAt e caminhos de armazenamento quando as imagens foram salvas.

​
Obter imagens do documento armazenadas

Se a verificação tiver imagens salvas (documentFrontStoragePath / documentBackStoragePath), 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 (ex.: Content-Type: image/jpeg). 404 se a verificação não existir ou esse lado não foi armazenado.

​
Convivência com outros fluxos KYC

  • Fluxo por sessão cria um registro em kyc_validations e usa uma URL hospedada; a decisão armazenada pode incluir documento, liveness e face match da sessão ao vivo.
  • Face Match compara foto do documento + selfie e retorna correspondência + pontuação; auditoria em face_match_verifications.
  • ID Verification valida o documento (frente/verso), extrai dados e retorna Aprovado/Recusado; auditoria em id_verification_verifications. Não cria registro em kyc_validations. Use quando precisar apenas de validação e extração do documento sem sessão hospedada.

​
Próximos passos

Face Match (Documento + Selfie)

Comparar documento e selfie

Criar validação KYC

Verificação por sessão com URL hospedada