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

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "userRef": "user-123",
  "status": "completed",
  "decision": "approved",
  "document": {
    "type": "passport",
    "number": "A12345678",
    "personalNumber": null,
    "issuingState": null,
    "issuingCountry": "USA",
    "issuingCountryName": "United States",
    "expirationDate": "2033-09-30",
    "dateOfIssue": null
  },
  "person": {
    "firstName": "ALEX",
    "lastName": "MORGAN",
    "fullName": "ALEX MORGAN",
    "dateOfBirth": "1988-03-04",
    "gender": "F",
    "nationality": "USA",
    "address": null,
    "city": null,
    "region": null,
    "postalCode": null
  },
  "checks": [
    { "name": "document_scene_clear",  "status": "passed", "group": "document", "severity": "low", "detail": "no screen-recapture signals" },
    { "name": "document_readable",     "status": "passed", "group": "document", "severity": "critical", "detail": "all core fields extracted" },
    { "name": "document_authentic",    "status": "passed", "group": "document", "severity": "high", "detail": "genuine — laminate sheen, crisp typography, natural depth" },
    { "name": "document_not_expired",  "status": "passed", "group": "document", "severity": "critical", "detail": "expirationDate 2033-09-30" },
    { "name": "document_number_valid", "status": "passed", "group": "document", "severity": "medium", "detail": "passport:USA — document number matches the USA passport format" },
    { "name": "document_mrz_valid",    "status": "passed", "group": "document", "severity": "low", "detail": "all check digits valid" },
    { "name": "face_detected",         "status": "passed", "group": "selfie",   "severity": "medium", "detail": "One face, fully visible and facing the camera." },
    { "name": "liveness",              "status": "passed", "group": "selfie",   "severity": "high", "detail": "heuristic (selfie mode): face confidence + quality vs threshold 80.0" },
    { "name": "face_match",            "status": "passed", "group": "selfie",   "severity": "high", "detail": "portrait-to-selfie similarity vs threshold 90.0" }
  ],
  "prefillMismatches": [],
  "prefillComparison": [],
  "provider": "inyo",
  "trustIndex": 100
}

Campos de Nível Superior

document

person

firstName, lastName, fullName, dateOfBirth, gender, nationality, address, city, region, postalCode.

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 e Decisão

São dois campos diferentes. status diz onde a sessão está; decision diz o que a Inyo concluiu, e só existe se você pediu que concluíssemos algo.

status — sempre presente

status nunca nomeia um veredito.

decision — somente no decisionamento gerenciado

Dois modos de decisionamento. Sob decisionamento não gerenciado — o padrão — a Inyo publica a avaliação e você decide: checks e trustIndex estão lá, e decision fica totalmente ausente do payload. Sob decisionamento gerenciado a Inyo também chega a um veredito, que é o campo decision, e pode encaminhar a sessão a um revisor humano antes.

A chave fica ausente, não null. "decision" in payload distingue "você nunca receberia uma decisão" de uma decisão que não conseguimos alcançar — esta última não existe.

Lendo checks[]

Cada checagem tem exatamente seis campos: name, status, group, severity, reason, detail.

O conjunto varia. As checagens aparecem apenas quando aplicáveis — uma zona de leitura automática exige um documento que a carregue, as checagens de rosto exigem uma selfie, várias são habilitadas por conta. Percorra o array; nunca o indexe por posição.

Duas formas de uma checagem não chegar a um veredito, e nenhuma delas é uma constatação contra o cliente. undetermined significa que ela rodou e não concluiu; not_evaluated significa que não obtivemos veredito algum — um provedor que não alcançamos, um dado que o documento não trouxe, uma captura recusada antes da vez dela. Ambas são cobradas como uma fração do peso da checagem, em vez de ignoradas, e reason diz qual foi o caso. Uma linha ausente é uma terceira coisa: a checagem nunca foi aplicável.

As Checagens

Uma linha por checagem. severity é configurável, então o quanto uma falha custa nas suas verificações é definido para a sua conta.

Comparação de Prefill

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

"prefillComparison": [
  { "field": "lastName",     "sent": "Silva",      "received": "SILVA SANTOS", "match": true,  "method": "subset",     "score": 0.95, "threshold": 0.85 },
  { "field": "dateOfBirth", "sent": "1988-03-04", "received": "1988-03-04",   "match": true,  "method": "exact",      "score": null, "threshold": null },
  { "field": "issuingState", "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 — o issuingState de um passaporte é um deles, já que nenhum passaporte evidencia subdivisão. Envie o país em issuingCountry, que é comparado. 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 dataCheck: true, o que adiciona a checagem document_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:

"selfieDescription": {
  "estimatedAgeLow": 30,
  "estimatedAgeHigh": 40,
  "skinTone": "light",
  "eyeColor": "brown",
  "hairColor": "dark brown",
  "hairStyle": "shoulder length, straight",
  "facialHair": "none",
  "eyewear": "none",
  "headwear": "none",
  "distinguishingFeatures": ["small scar above left eyebrow"],
  "notes": null
}

Qualquer atributo que não possa ser observado é null.

Descrições de aparência são dados pessoais sensíveis. Elas carregam exposição a GDPR e a leis de privacidade biométrica (por exemplo, BIPA), e a selfie é processada por um serviço de visão externo. Confirme que você tem base legal, um acordo de processamento de dados em vigor e uma justificativa de retenção documentada antes de nos pedir para ativar isso.

Triagem de Sanções

Desligada por padrão, e habilitada por tenant pela Inyo quando solicitado. Quando ativa, o nome extraído do documento é triado contra a lista OFAC de Nacionais Especialmente Designados (SDN).

Um nome que coincide não é uma pessoa

Dois tokens de nome comuns aparecem em muitos nomes listados, então uma coincidência de nome por si só nunca recusa. A confirmação é pela data de nascimento, e o resultado é o status da única checagem sanctions_clear:

Nada ambíguo é resolvido em direção à aprovação. Baseie decisões em status. O limiar de aceitação é configurado por tenant — pergunte ao seu contato na Inyo qual é o seu.

O bloco screening

Presente apenas quando houve uma coincidência entregue — ou seja, junto de um sanctions_clear que está failed (coincidência confirmada) ou undetermined (não confirmada). Está ausente quando a triagem sai limpa, portanto sua presença significa "há algo a adjudicar", não "a triagem foi executada".

"screening": {
  "matches": [
    {
      "name": "SAMPLE, Ali Hassan",
      "sourceList": "us_ofac",
      "programs": ["SDGT"],
      "entityId": "12345",
      "score": 91.5,
      "dobAgrees": true
    }
  ]
}

No máximo cinco coincidências são entregues — o suficiente para distinguir uma coincidência única plausível de um agrupamento óbvio de colisões. Apenas candidatos no seu limiar ou acima aparecem.

Uma peculiaridade que vale saber na adjudicação: a OFAC publica datas imprecisas colapsadas em 1º de janeiro, então um candidato listado nesse dia é comparado apenas pelo ano. Para quem nasceu genuinamente em 1º de janeiro isso afrouxa a correspondência, na direção da recusa.

Seu cliente nunca é informado de que uma coincidência de sanções foi o que o rejeitou. A resposta de recusa é idêntica byte a byte a qualquer outra falha sem nova tentativa.

Se a triagem estiver indisponível

A triagem falha aberta: uma indisponibilidade do provedor pula a checagem em vez de bloquear ou recusar a verificação. Nada no resultado entregue distingue uma sessão que seguiu sem triagem de uma que foi triada e saiu limpa — nesse caso simplesmente não existe nenhuma linha sanctions_clear. Se você precisa de evidência positiva de que toda verificação foi triada, verifique a presença dessa checagem, não a ausência de coincidência.

Próximos Passos

• Revisão Manual — o que significa in_review e como uma decisão muda
• Recebendo Resultados — como esse payload chega até você