Checagens e Decisões

Toda verificação — via widget ou servidor-a-servidor — resolve para o mesmo resultado normalizado. Esta página é a referência para interpretá-lo.

O Payload de Resultado

{
  "session_id": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "user_ref": "user-123",
  "status": "approved",
  "auto_status": "approved",
  "document": {
    "type": "Passport",
    "number": "A12345678",
    "personal_number": null,
    "issuing_state": "USA",
    "issuing_country": "USA",
    "issuing_country_name": "United States",
    "expiration_date": "2033-09-30",
    "date_of_issue": null
  },
  "person": {
    "first_name": "ALEX",
    "last_name": "MORGAN",
    "full_name": "ALEX MORGAN",
    "date_of_birth": "1988-03-04",
    "gender": "F",
    "nationality": "USA",
    "address": null,
    "city": null,
    "region": null,
    "postal_code": null
  },
  "checks": [
    { "name": "document_authentic",   "passed": true, "score": null, "detail": "no screen-recapture signals" },
    { "name": "document_readable",    "passed": true, "score": null, "detail": "all core fields extracted" },
    { "name": "mrz_valid",            "passed": true, "score": null, "detail": "all check digits valid" },
    { "name": "document_not_expired", "passed": true, "score": null, "detail": "expiration_date 2033-09-30" },
    { "name": "document_number_format", "passed": true, "score": null, "detail": "passport:USA — document number matches the USA passport format" },
    { "name": "screen_pattern",       "passed": true, "score": null, "detail": "screen/moiré score 0.42 vs threshold 0.8" },
    { "name": "ai_authenticity",      "passed": true, "score": 95.0, "detail": "genuine document — physical document, consistent printing" },
    { "name": "face_detected",        "passed": true, "score": null, "detail": "eyes_open=True sunglasses=False frontal=True" },
    { "name": "liveness",             "passed": true, "score": 93.2, "detail": "heuristic (selfie mode): face confidence + quality vs threshold 80.0" },
    { "name": "face_match",           "passed": true, "score": 98.7, "detail": "CompareFaces similarity vs threshold 90.0" }
  ],
  "prefill_mismatches": [],
  "prefill_comparison": [],
  "selfie_description": null,
  "provider": "inyo"
}

Campos de Nível Superior

document

person

first_name, last_name, full_name, date_of_birth, gender, nationality, address, city, region, postal_code.

Qualquer campo que o documento não traga — ou que não pôde ser lido — é null. Campos de endereço são comumente null em passaportes e preenchidos a partir de carteiras de motorista. Os nomes chegam como impressos no documento, o que em passaportes significa letras maiúsculas.

Status

Lendo checks[]

Toda checagem tem exatamente quatro campos: name, passed, score, detail.

Duas checagens exigem tratamento explícito:

screen_pattern carrega score: null deliberadamente. Sua medição subjacente opera em uma escala invertida de 0-1 onde valores maiores significam mais parecido com tela, o que pareceria uma quase-falha ao lado das biometrias de 0-100. Publicá-la como score induziria mais ao erro do que informaria, então o valor bruto e seu limiar ficam em detail. Leia passed.

ai_authenticity carrega uma pontuação que você não deve usar como critério de decisão. A pontuação é a certeza do modelo em seu próprio veredito, orientada de modo que valores maiores significam "mais provavelmente genuíno". É apenas diagnóstica — a Inyo a exclui deliberadamente do roteamento de revisão. Isso não torna a checagem inerte: é uma checagem hard, e passed: false recusa a verificação de imediato, independentemente do que a pontuação diga.

As Checagens

Checagens hard reprovam a verificação — a falha de qualquer uma delas resulta em declined.

Checagens soft encaminham a verificação para in_review em vez de recusá-la.

Uma checagem adicional aparece apenas no fluxo do widget: capture_attempts falha quando o cliente esgotou o limite de tentativas, o que recusa a sessão — veja Entrega via Widget.

Comparação de Prefill

Quando você envia prefill, o resultado relata como cada campo comparável se alinhou. prefill_mismatches é a lista curta de nomes de campos que divergiram; prefill_comparison traz o detalhe:

"prefill_comparison": [
  { "field": "last_name",     "sent": "Silva",      "received": "SILVA SANTOS", "match": true,  "method": "subset",     "score": 0.95, "threshold": 0.85 },
  { "field": "date_of_birth", "sent": "1988-03-04", "received": "1988-03-04",   "match": true,  "method": "exact",      "score": null, "threshold": null },
  { "field": "issuing_state", "sent": "Florida",    "received": "FL",           "match": true,  "method": "normalized", "score": null, "threshold": null }
]

Campos ausentes em qualquer um dos lados não são comparados, então nunca aparecem. Nomes usam correspondência fuzzy — acentos removidos, sobrenomes compostos aceitos como correspondências de subconjunto, erros próximos de OCR tolerados até o limiar — de modo que variações comuns de grafia não criam falsas divergências. Estados e tipos de documento são normalizados primeiro, e é por isso que Florida corresponde a FL.

Uma divergência só afeta a decisão quando você define data_check: true, o que adiciona a checagem soft data_match. Sem isso, a comparação é apenas informativa.

Descrição da Selfie

null a menos que a descrição de aparência esteja habilitada para o seu tenant. Quando presente, traz atributos observáveis da selfie para comparação em reverificações futuras:

"selfie_description": {
  "estimated_age_low": 30,
  "estimated_age_high": 40,
  "skin_tone": "light",
  "eye_color": "brown",
  "hair_color": "dark brown",
  "hair_style": "shoulder length, straight",
  "facial_hair": "none",
  "eyewear": "none",
  "headwear": "none",
  "distinguishing_features": ["small scar above left eyebrow"],
  "notes": null
}

Qualquer atributo que não possa ser observado é null. Esses são dados pessoais sensíveis — veja a nota de conformidade em Configuração do Tenant antes de habilitá-la.

Transição da Convenção de Pontuação

Resultados criados antes do lançamento da convenção de pontuação atual diferem em dois aspectos: screen_pattern.score carregava uma probabilidade bruta de moiré de 0-1 (onde maior significava pior), e ai_authenticity.score usava uma escala indefinida. Registros pós-transição são identificáveis sem referência externa — screen_pattern.score é null, e nenhuma checagem carrega qualquer campo além dos quatro documentados acima. Se você armazena resultados históricos, baseie sua leitura nisso.

Próximos Passos

• Revisão Manual — in_review, auto_status e manual_review
• Configuração do Tenant — os limiares contra os quais essas checagens são comparadas
• Recebendo Resultados — como esse payload chega até você