Documents and biometrics

This guide explains best practices for structuring customer journeys and handling JSON schemas when combining:

• Document modules
• Liveness module
• Facematch module

​

Recommended module sequence

A typical customer journey flow for documents and biometrics involves sequencing modules in the following pattern:

• Document first: Establishes the identity baseline for capturing and validating official documents, such as drivers license and passports. Document verification typically involves three main modules:

  • Document Classification
  • Document Authentication
  • Document Extraction

  To learn about the best practices for module sequencing, check out the Best practices for ordering document modules in GBG GO guide.

• Liveness second: Ensures the person submitting the document is physically present and not using a static image. The Liveness module captures a live selfie or video to confirm the user’s presence.

• Facematch last: Confirms that the person in the live selfie matches the document photo. The Facematch module compares the live image with the document image to ensure they are from the same individual.

Another recommended sequence is Liveness → Document → Facematch. This approach captures proof of life first, then documents, and concludes with facial comparison.

Regardless of the sequence you choose, it’s important that facematch comes after document verification to ensure proper identity confirmation.

Check out our web capture SDK for implementing liveness and documents capture in your web applications.

​

JSON schema structure

This section examines the data schema structure that is created when the documents and biometrics modules are combined in a customer journey and published in the GBG GO platform.

These schemas define the payload structure when invoking the /journey/start endpoint in prefill mode, where document and biometric data are mapped to their respective properties within the context object. For example:

{
  "resourceId": "your-journey-resourceId@latest",
  "context": {
    "subject": {
      "identity": {
        "firstName": "Sarah",
        "lastName": "Johnson",
        "dateOfBirth": "1990-05-15"
      },
      "documents": [
        {
          "side1Image": "String or Binary",
          "side2Image": "String or Binary"
        }
      ],
      "biometrics": [
        {
          "selfieImage": "String or Binary",
          "anchorImage": "String or Binary"
        }
      ]
    }
  }
}

In the biometrics schema, selfieImage is captured from liveness verification, while anchorImage handling depends on the journey configuration.

For example, if a customer journey includes all three of the documents and biometrics modules, the anchorImage is auto-populated by the Document Extraction Module, requiring your customers to provide only the selfieImage.

However, for journeys containing only Liveness and Facematch modules, customers must provide both selfieImage and anchorImage.

​

Document schema

This is the standard schema for the document modules:

"documents": [
 {
   "side1Image": "String or Binary",
   "side2Image": "String or Binary"
 }
]

​

Biometrics schema

This is the standard schema for Liveness and Facematch modules:

"biometrics": [
  {
    "selfieImage": "String or Binary",
    "anchorImage": "String or Binary"
  }
]

​

Key terminologies

• selfieImage: The live photo captured during liveness verification.
• anchorImage: The trusted reference image that serves as the comparison baseline, sourced either from the provided document or from the customer’s existing verified image (such as a previously verified selfie retained in their CRM systems).
• side1Image: Primary document image (usually the front side containing the photo).
• side2Image: Secondary document image (back side, if applicable).