Verificaciones y decisiones

Toda verificación — por widget o servidor a servidor — se resuelve en el mismo resultado normalizado. Esta página es la referencia para interpretarlo.

El 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 nivel superior

document

person

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

Cualquier campo que el documento no incluya — o que no pudo leerse — es null. Los campos de dirección suelen ser null en pasaportes y se completan a partir de licencias de conducir. Los nombres llegan tal como están impresos en el documento, lo que en pasaportes significa en mayúsculas.

Estado y Decisión

Son dos campos distintos. status dice dónde está la sesión; decision dice lo que Inyo concluyó, y solo existe si usted pidió que concluyéramos algo.

status — siempre presente

status nunca nombra un veredicto.

decision — solo en decisionamiento gestionado

Dos modos de decisionamiento. Bajo decisionamiento no gestionado — el predeterminado — Inyo publica la evaluación y usted decide: checks y trustIndex están ahí, y decision está totalmente ausente del payload. Bajo decisionamiento gestionado Inyo además llega a un veredicto, que es el campo decision, y puede enrutar la sesión a un revisor humano antes.

La clave queda ausente, no null. "decision" in payload distingue "nunca le íbamos a dar una decisión" de una decisión que no pudimos alcanzar — esta última no existe.

Cómo leer checks[]

Cada verificación tiene exactamente seis campos: name, status, group, severity, reason, detail.

El conjunto varía. Las verificaciones aparecen solo cuando son aplicables — una zona de lectura mecánica requiere un documento que la lleve, las de rostro requieren una selfie, varias se habilitan por cuenta. Recorra el arreglo; nunca lo indexe por posición.

Dos formas en que una verificación no llega a un veredicto, y ninguna es una constatación contra el cliente. undetermined significa que se ejecutó y no pudo concluir; not_evaluated significa que nunca obtuvimos veredicto — un proveedor inalcanzable, un dato que el documento no traía, una captura rechazada antes de su turno. Ambas se cobran como una fracción del peso de la verificación, en vez de ignorarse, y reason dice cuál fue. Una fila ausente es una tercera cosa: la verificación nunca fue aplicable.

Las verificaciones

Una fila por verificación. severity es configurable, así que cuánto cuesta una falla en sus verificaciones se define para su cuenta.

Comparación de prefill

Cuando usted envía prefill, el resultado reporta cómo coincidió cada campo comparable. prefillMismatches es la lista corta de nombres de campos que no coincidieron; prefillComparison incluye el detalle:

"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 }
]

Los campos ausentes en cualquiera de los dos lados no se comparan, así que nunca aparecen — el issuingState de un pasaporte es uno de ellos, ya que ningún pasaporte evidencia subdivisión. Envíe el país en issuingCountry, que sí se compara. Los nombres usan coincidencia difusa — acentos eliminados, apellidos compuestos aceptados como coincidencias de subconjunto, errores cercanos de OCR tolerados hasta el umbral — de modo que la variación ortográfica ordinaria no crea falsos desacuerdos. Los estados y tipos de documento se normalizan primero, y por eso Florida coincide con FL.

Un desacuerdo solo afecta la decisión cuando usted establece dataCheck: true, lo que agrega la verificación document_data_match. Sin eso, la comparación es informativa.

Descripción de la selfie

null a menos que la descripción de apariencia esté habilitada para su tenant. Cuando está presente, incluye atributos observables de la selfie para una comparación posterior de re-verificación:

"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
}

Cualquier atributo que no pueda observarse es null.

Las descripciones de apariencia son datos personales sensibles. Conllevan exposición bajo el RGPD y leyes de privacidad biométrica (por ejemplo BIPA), y la selfie es procesada por un servicio de visión externo. Confirme que tiene una base legal, un acuerdo de procesamiento de datos vigente y una justificación de retención documentada antes de pedirnos habilitar esto.

Cribado de sanciones

Desactivado por defecto, y habilitado por tenant por Inyo cuando se solicita. Cuando está activo, el nombre extraído del documento se criba contra la lista OFAC de Nacionales Especialmente Designados (SDN).

Un nombre que coincide no es una persona

Dos tokens de nombre comunes aparecen en muchos nombres listados, así que una coincidencia de nombre por sí sola nunca rechaza. La confirmación es por fecha de nacimiento, y el resultado es el status de la única verificación sanctions_clear:

Nada ambiguo se resuelve hacia la aprobación. Base sus decisiones en status. El umbral de aceptación se configura por tenant — consulte a su contacto en Inyo cuál es el suyo.

El bloque screening

Presente solo cuando se entregó una coincidencia — es decir, junto a un sanctions_clear que está failed (coincidencia confirmada) o undetermined (sin confirmar). Está ausente cuando el cribado sale limpio, por lo que su presencia significa "hay algo que adjudicar", no "el cribado se ejecutó".

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

Se entregan como máximo cinco coincidencias — suficientes para distinguir una coincidencia única plausible de un grupo obvio de colisiones. Solo aparecen candidatos en su umbral o por encima.

Una particularidad que conviene saber al adjudicar: OFAC publica fechas imprecisas colapsadas al 1 de enero, así que un candidato listado en ese día se compara solo por año. Para quien nació genuinamente el 1 de enero eso afloja la correspondencia, en dirección al rechazo.

Su cliente nunca sabe que una coincidencia de sanciones fue lo que lo rechazó. La respuesta de rechazo es idéntica byte a byte a cualquier otro fallo sin reintento.

Si el cribado no está disponible

El cribado falla abierto: una caída del proveedor omite la verificación en vez de bloquear o rechazar. Nada en el resultado entregado distingue una sesión que se entregó sin cribar de una que se cribó y salió limpia — en ese caso simplemente no existe ninguna fila sanctions_clear. Si necesita evidencia positiva de que toda verificación fue cribada, compruebe la presencia de esa verificación, no la ausencia de coincidencia.

Próximos pasos

• Revisión Manual — qué significa in_review y cómo cambia una decisión
• Recepción de Resultados — cómo le llega este payload