Skip to main content
Version: v3

Checks

A check is one verification unit. For example, a check might tell you that the document is a photocopy, or that the date of birth printed on the front doesn't match the one encoded in the barcode.

Verify has numerous checks, and they abstractly represent the underlying fraud detection logic and our AI models. Related checks are grouped together, so a group's result summarizes everything below it.

For example, screen presence and photocopy are both document liveness checks, and together they tell you whether the document was physically present.

How checks are structured​

Checks live in the verification.checks object of the response. It is a typed object with four groups, each of which is itself a check:

{
  "verification": {
    "checks": {
      "extractedDataCheck": { "result": "Fail" },
      "documentLivenessCheck": { "result": "Pass" },
      "visualCheck": { "result": "Pass" },
      "documentValidityCheck": { "result": "Pass" }
    }
  }
}

Every check is an object with an overall result and sub-checks:

{
  "verification": {
    "checks": {
      "extractedDataCheck": {
        "result": "Fail",
        "mrzCheck": {
          "result": "Fail",
          "parsedCheck": { "result": "Pass" },
          "checkDigitsCheck": { "result": "Fail" }
        }
      }
    }
  }
}

Check results​

Every check resolves to one of three values in its result field:

  • Pass: the check ran and the document passed it.
  • Fail: the check ran and the document failed it.
  • NotPerformed: the check didn't run, for example because the document doesn't carry the data it needs, or because you disabled it.

Extracted data checks​

checks.extractedDataCheck covers everything derived from the data read off the document. This ranges from simple questions, such as whether the dates are in a logical order, to composites of hundreds of internal checks, such as barcode authenticity on AAMVA documents.

It has six children:

  • matchCheck: if data is read from more than one place on the document, does the same data match; for example does information from the visual inspection zone correspond to the information from the MRZ.
  • logicCheck: whether the values make sense, for example is the date on the document a possible date; includes general document logic, like check digits or document field rules.
  • formatCheck: whether each field's value has the shape its issuer prescribes.
  • barcodeAuthenticityCheck: whether the document's barcode is genuine.
  • mrzCheck: whether the machine-readable zone is sound.
  • genericDataCheck: checks whether or not the data on the document is generic, for example "Sample Specimen".

Document liveness checks​

checks.documentLivenessCheck tells you whether a physical document was in front of the camera, or if it was a non-physical representation. The passive liveness approach comes down to two checks, powered by various AI models:

  • screenPresenceCheck: whether the document is being presented on a screen.
  • photocopyCheck: whether the document is a photocopy.

Hand presence is reported separately, as imageAssessment.handPresenceCheck.

Visual checks​

checks.visualCheck represents the visual fraud checks. It doesn't cover visual problems that aren't fraud, such as glare or blur; those belong to image assessment.

It has three children:

  • portraitForgeryCheck: whether the portrait (face image) has been tampered with.
  • securityFeaturesCheck: whether the document's static security features are as expected.
  • generativeAiCheck: whether the image, document, or a part of it, was generated by an AI model.

Document validity checks​

checks.documentValidityCheck covers whether the document is usable for identification at all, regardless of whether it's genuine.

It has two children:

  • expiredCheck: whether this particular document has expired.
  • discontinuedDocumentCheck: whether this type of document is still acceptable in its jurisdiction today, regardless of its own expiry date.

Image assessment isn't a check group​

Image-related assessment sits outside verification.checks, in the top-level imageAssessment object. It holds three checks:

  • imageQualityCheck: the combined output of the heuristics and models that decide whether the captured images are good enough to verify.
  • croppedDocumentCheck: whether a side is fully cropped, with no surrounding background. See how to accept cropped images.
  • handPresenceCheck: whether a hand is holding or occluding the document.

It's the place to look when a verdict is Retry, because it usually explains why a new image would help. The messages response field will also surface relevant information in this case (see Messages).

Last updated on