Skip to main content
This guide explains best practices for structuring customer journeys and handling JSON schemas when combining:
  • Document modules
  • Liveness module
  • Facematch module
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 driver’s licenses and passports. Document verification typically involves three main modules:
    • Document Classification
    • Document Authentication
    • Document Extraction
    To learn about the best practices for module sequencing, refer to the Group documents modules 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.
These are recommended patterns only. You can sequence modules according to your specific use cases and business requirements.

​
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:
JSON
{
  "resourceId": "your-journey-resourceId@latest",
  "context": {
    "subject": {
      "identity": {
        "firstName": "Sarah",
        "lastName": "Johnson",
        "dateOfBirth": "1990-05-15"
      },
      "documents": [
        {
          "side1Image": "Base64-encoded string or binary data",
          "side2Image": "Base64-encoded string or binary data"
        }
      ],
      "biometrics": [
        {
          "selfieImage": "Base64-encoded string or binary data",
          //anchorImage is only required for Facematch-only or combined Facematch and Liveness journeys. For Liveness-only journeys, omit the anchorImage field.
          "anchorImage": "Base64-encoded string or binary data"
        }
      ]
    }
  }
}
In the biometrics schema, selfieImage is captured from the Liveness module. The anchorImage is automatically populated from the document modules after extraction by the Document Extraction module. You do not need to pass the anchorImage in pre-fill mode. The system automatically uses the extracted document image as the anchor for facematch comparisons. This simplifies the integration and ensures that the correct reference image is used for biometric verification.
The fields you need to provide depend on which modules your journey uses:
  • Liveness only: Pass only selfieImage. The anchorImage is not required.
  • Facematch only: Pass both selfieImage and anchorImage.
  • Liveness + Facematch: Pass both selfieImage and anchorImage.
  • Documents + Biometrics: Pass side1Image and side2Image (if applicable) for document verification, along with selfieImage.

​
Document schema

This is the standard schema for the document modules:
JSON
"documents": [
 {
   "side1Image": "Base64-encoded string or binary data",
   "side2Image": "Base64-encoded string or binary data"
 }
]
side2Image is only required for documents that have information on both sides (example: driver’s licenses and national ID cards).

​
Biometrics schema

This is the standard schema for Liveness and/or Facematch modules:
JSON
"biometrics": [
  {
    "selfieImage": "String or Binary",
    "anchorImage": "String or Binary"
  }
]
anchorImage is only required when using Facematch, either standalone or combined with Liveness modules. For Liveness-only journeys, you only need to provide selfieImage.

​
Supported file formats

GBG GO supports the following file formats for document and biometric image uploads:
  • PNG
  • JPEG
  • BMP
HEIC format is not supported for document and biometric image uploads. If you attempt to upload an HEIC file, the system returns an error.

​
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).