User Data Schema - GBG Documentation

Understand the context object and schema

When integrating with the GBG GO API, you will pass customer data using the context object. This object contains structured information required for identity verification, document processing, and biometric validation.

What is the context object?

The context object is a structured data model that holds customer details and other metadata needed during a journey. It consists of multiple nested objects, each representing different aspects of the customer’s identity and verification details.

The primary sections of the context object include:

subject – Contains identity information, documents, and biometrics related to the customer.
device – Provides device-related metadata, such as IP address.
metadata – Stores additional details related to the journey.

Where does the schema come from?

Each customer journey is designed in the GBG GO platform, and every published journey has a schema that defines the expected structure of the context object.

You should:

Retrieve the schema for a journey from the Journey Dashboard in the GBG GO platform.
Use the schema as the source of truth when structuring API requests.
Ensure that data types and required fields match those defined in the schema.

Why is the schema important?

It dictates the format in which data should be sent.
It ensures compatibility between the API and the verification modules.
It reduces errors by validating input data before submission.

Key objects in the context schema

The schema defines multiple objects within the context, each containing required and optional fields, such as:

Identity Object – Contains personal details such as name, date of birth, and contact information.
Documents Object – Holds information about identity documents, including images and classification details.
Biometrics Object – Stores biometric data such as face images used for verification.

The schema may vary depending on the journey configuration. Always refer to the schema retrieved from the Journey Dashboard for the most up-to-date structure.

How to use the table below

The following table provides a detailed breakdown of all possible fields in the context object. It includes field names, descriptions, expected data types, and whether the field is required or optional. Use this reference when constructing API requests to ensure all necessary data is included in the correct format:

Person

Property	Type	Description
title	Title	Title of the individual
firstName	FirstName	Given name of the individual
middleNames	MiddleNames	Any additional registered names
lastNames	LastNames	Family names of the individual
lastNamesAtBirth	LastNames	Family names at birth
aliases	array of NamesObject	Alternative names used by the person
relatedPersons	array of RelatedPerson	Related persons with relationship type
dateOfBirth	Date	Birth date of the individual
gender	Gender	Gender of the individual
currentAddress	Address	Current residence of the individual
previousAddresses	array of PreviousAddress	Past residences with date range
placeOfBirth	Address	Birthplace of the individual
idNumbers	array of IdNumbers	Identification numbers
phones	array of Phones	Contact numbers
emails	array of Emails	Email addresses
socials	array of Socials	Social media accounts

Sample Data

{
  "title": "Mr",
  "firstName": "David",
  "middleNames": ["James"],
  "lastNames": ["Jones"],
  "lastNamesAtBirth": ["Smith"],
  "aliases": [
    {
      "firstName": "Dave",
      "lastNames": ["Johnson"]
    }
  ],
  "relatedPersons": [
    {
      "relationship": "mother",
      "firstName": "Sarah",
      "lastNames": ["Jones"]
    }
  ],
  "dateOfBirth": "1985-06-15",
  "gender": "Male",
  "currentAddress": {
    "addressString": "128 Queen Victoria Street, London, EC4V 4BJ, GBR"
  },
  "previousAddresses": [
    {
      "address": {
        "addressString": "45 Oxford St, Manchester, M1 5AN, GBR"
      },
      "dateRange": {
        "fromDate": "2000-01-01",
        "toDate": "2010-12-31"
      }
    }
  ],
  "placeOfBirth": {
    "locality": "London",
    "country": "GBR"
  },
  "idNumbers": [
    {
      "type": "SSN",
      "idNumber": "AAA-GG-SSSS"
    }
  ],
  "phones": [
    {
      "type": "mobile",
      "number": "+44 207 4281250"
    }
  ],
  "emails": [
    {
      "type": "work",
      "email": "david.jones@company.com"
    }
  ],
  "socials": [
    {
      "type": "LinkedIn",
      "identity": "davidjones123"
    }
  ]
}

Supporting Schemas

RelatedPerson

Property	Type	Description
relationship	string	Relationship type (e.g., `"mother"`, `"father"`, `"maternalGrandFather"`, etc.)
title	Title	Title of the related person
firstName	FirstName	Given name of the related person
middleNames	MiddleNames	Additional registered names of the related person
lastNames	LastNames	Family names of the related person
lastNamesAtBirth	LastNames	Family names at birth of the related person

PreviousAddress

Property	Type	Description
address	Address	Address object
dateRange	DateRange	Date range object specifying the duration of residence

Phones

Property	Type	Description	Example
type	string	Type of phone (landline, mobile, fax, etc.)	`"mobile"`
number	string	Phone number in international format	`"+44 207 4281250"`

Sample Data

[
  {
    "type": "mobile",
    "number": "+44 207 4281250"
  }
]

IdNumbers

Property	Type	Description	Example
type	string	Type of ID (e.g., SSN)	`"SSN"`
idNumber	string	The ID number itself	`"AAA-GG-SSSS"`

Sample Data

[
  {
    "type": "SSN",
    "idNumber": "AAA-GG-SSSS"
  }
]

Emails

Property	Type	Description	Example
type	string	Type of email (home, work, etc.)	`"home"`
email	string	Email address	`"person.name@domain.com"`

Sample Data

[
  {
    "type": "home",
    "email": "person.name@domain.com"
  }
]

Socials

Property	Type	Description	Example
type	string	Social media platform	`"Facebook"`
identity	string	User’s handle on the platform	`"myName123456"`

Sample Data

[
  {
    "type": "Facebook",
    "identity": "myName123456"
  }
]

Address

Property	Type	Description	Example
lines	array of strings	Address in multiple lines	`["128 Queen Victoria Street", "London"]`
addressString	string	Address in a single line	`"128 Queen Victoria Street, London, EC4V 4BJ, GBR"`
premise	string	Building number	`"128"`
thoroughfare	string	Street name	`"Queen Victoria Street"`
locality	string	City or town	`"London"`
postalCode	string	Postal or ZIP code	`"EC4V 4BJ"`
country	string	ISO2 or ISO3 country code	`"GBR"`
organization	string	Associated company or organization	`"GB Group"`

Sample Data

{
  "addressString": "128 Queen Victoria Street, London, EC4V 4BJ, GBR",
  "locality": "London",
  "country": "GBR",
  "postalCode": "EC4V 4BJ",
  "organization": "GB Group"
}

Title

Property	Type	Description	Example
title	string	Honorific title (Mr, Mrs, Dr, etc.)	`"Mr"`

Sample Data

{
  "title": "Mr"
}

FirstName

Property	Type	Description	Example
firstName	string	Given name of the person	`"David"`

MiddleNames

Property	Type	Description	Example
middleNames	array of strings	Additional registered names	`["James"]`

Sample Data

{
  "middleNames": ["James"]
}

LastNames

Property	Type	Description	Example
lastNames	array of strings	Family names	`["Jones"]`

Sample Data

{
  "lastNames": ["Jones"]
}

NamesObject

Property	Type	Description	Example
title	string	Title of the individual	`"Mr"`
firstName	string	Given name	`"David"`
middleNames	array of strings	Additional registered names	`["James"]`
lastNames	array of strings	Family names	`["Jones"]`
lastNamesAtBirth	array of strings	Family names at birth	`["Smith"]`

Sample Data

{
  "title": "Mr",
  "firstName": "David",
  "middleNames": ["James"],
  "lastNames": ["Jones"],
  "lastNamesAtBirth": ["Smith"]
}

Gender

Property	Type	Description	Example
gender	string	Gender of the individual	`"Male"`

DateTime

An ISO 8601 timestamp, with no optional bits:

Hyphens MUST be used to separate the date components.
Day and month should be 2 digits.
Colons MUST be used to separate the time components.
Timestamps MUST NOT contain milliseconds.
Timestamp MUST indicate the timezone, either as a time offset or a Zulu time indicator.

Property	Type	Format	Pattern
DateTime	string	date-time	`^\d-\d-\dT\d:\d:\d(([+-]\d:\d)	Z)$`

Sample Data

"2019-01-04T14:38:25Z"

TimeRange

Property	Type	Description
start	DateTime	Start timestamp
end	DateTime	End timestamp

Sample Data

{
  "start": "2023-06-15T08:30:00Z",
  "end": "2023-06-15T17:00:00Z"
}

Date

Property	Type	Description
Date	string	Specified in year, month, and day separated by `-` (ISO 8601 format)

Sample Data

"2000-01-01"

DateRange

Property	Type	Description
fromDate	Date	Start date
toDate	Date	End date

Sample Data

{
  "fromDate": "2015-05-10",
  "toDate": "2020-12-31"
}

Location

Property	Type	Description
latitude	string	Latitude of the location
longitude	string	Longitude of the location
geoAccuracy	string	Accuracy of the geolocation data
what3words	string	A What3Words designation with `.` separator

Sample Data

{
  "latitude": "51.5074",
  "longitude": "-0.1278",
  "geoAccuracy": "high",
  "what3words": "bearable.expecting.comical"
}

ResponseErrors

Response errors returned by any GBG service.

Property	Type	Description
correlationId	string	Unique UUID for the transaction related to the error
errors	array	List of processing issues

Sample Data

{
  "correlationId": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
  "errors": [
    {
      "location": "Authorization",
      "code": 1106,
      "problem": "The token is invalid",
      "action": "Please pass a valid token for access"
    }
  ]
}

StandardisedError

Property	Type	Description
location	string	Where the error occurred
code	integer	Error code
problem	string	Description of the issue
action	string	Suggested action to resolve the issue

Sample Data

{
  "location": "Authorization",
  "code": 1106,
  "problem": "The token is invalid",
  "action": "Please pass a valid token for access"
}

Next, lets proceed to the Identity Documents Schema

IdentityDocument

Property	Type	Description
id	string	Unique identifier for the identity document
device	CaptureDeviceInfo	Information about the device used for document capture
side1Image	string	Image of the front side of the document
side2Image	string	Image of the back side of the document
mrz	string	Machine-readable zone (MRZ) extracted from the document
classification	DocumentClassificationInfoV1	Classification details of the document
extraction	DocumentExtractionInfoV1	Extracted information from the document
validation	DocumentValidationInfoV1	Validation details of the document
category	string	General category of the document (e.g., passport, ID card)
type	string	Specific type of document
subType	string	Sub-type of the document
format	string	Format of the document
number	string	Unique identification number on the document
issueDate	string (date)	Date when the document was issued
expiryDate	string (date)	Date when the document expires
subject	Identity	Personal details of the document holder
country	Country	Country of issuance (ISO 3166-1 alpha-2 country code)

Sample Data

{
  "id": "123456",
  "device": {
    "type": "scanner",
    "model": "Canon DR-C225",
    "hasContactlessReader": false,
    "hasMagneticStripeReader": false,
    "hasCamera": true,
    "serialNumber": "ABC123456",
    "manufacturer": "Canon"
  },
  "side1Image": "https://example.com/front.jpg",
  "side2Image": "https://example.com/back.jpg",
  "mrz": "P<GBRJONES<<DAVID<<<<<<<<<<<<<<<<<<<<<<<<<1234567890GBR850101M2501017<<<<<<<<<<<<<<04",
  "classification": {
    "ids": ["1234"],
    "category": "Passport",
    "type": "National ID",
    "subtype": "Standard",
    "isDoubleSided": true,
    "hasNFC": false,
    "year": "2020",
    "countryCode": "GB",
    "countryName": "United Kingdom",
    "stateCode": "ENG",
    "stateName": "England",
    "sides": [
      {
        "side": "front",
        "id": "front-id",
        "documentQuality": "good",
        "documentQualityScore": 95
      }
    ]
  },
  "extraction": {
    "aggregatedFields": [
      {
        "label": "Document Number",
        "value": "1234567890",
        "source": "OCR",
        "isNonLatin": false,
        "regionOfInterest": {
          "boundingBox": {
            "x": 100,
            "y": 50,
            "width": 300,
            "height": 100
          },
          "side": "front",
          "spectrum": "visible",
          "imageId": "img-001"
        }
      }
    ],
    "extractedFields": [
      {
        "label": "Full Name",
        "details": [
          {
            "label": "First Name",
            "value": "David",
            "source": "OCR"
          },
          {
            "label": "Last Name",
            "value": "Jones",
            "source": "OCR"
          }
        ]
      }
    ]
  },
  "validation": {
    "validationChecks": [
      {
        "name": "MRZ Check",
        "title": "Machine Readable Zone Validation",
        "info": "Verifies MRZ matches document details",
        "validationResult": "Passed",
        "resultInfo": "Valid MRZ format",
        "weight": "High",
        "regionOfInterests": [
          {
            "boundingBox": {
              "x": 50,
              "y": 200,
              "width": 250,
              "height": 50
            },
            "side": "back",
            "spectrum": "visible",
            "imageId": "img-002"
          }
        ],
        "type": "Security Check"
      }
    ]
  },
  "category": "Passport",
  "type": "International",
  "subType": "Standard",
  "format": "Biometric",
  "number": "A12345678",
  "issueDate": "2015-06-15",
  "expiryDate": "2025-06-15",
  "subject": {
    "firstName": "David",
    "lastName": "Jones",
    "dateOfBirth": "1985-01-01",
    "gender": "Male",
    "nationality": "GBR"
  },
  "country": "GB"
}

CaptureDeviceInfo

Property	Type	Description
type	string	Type of device used for document capture (e.g., scanner, camera)
model	string	Model name of the device
hasContactlessReader	boolean	Indicates if the device has a contactless reader
hasMagneticStripeReader	boolean	Indicates if the device has a magnetic stripe reader
hasCamera	boolean	Indicates if the device has a camera
serialNumber	string	Serial number of the device
manufacturer	string	Name of the manufacturer

Sample Data

{
  "type": "scanner",
  "model": "Canon DR-C225",
  "hasContactlessReader": false,
  "hasMagneticStripeReader": false,
  "hasCamera": true,
  "serialNumber": "ABC123456",
  "manufacturer": "Canon"
}

DocumentClassificationInfoV1

Property	Type	Description
ids	array of strings	List of document classification identifiers
category	string	General category of the document (e.g., Passport, ID Card)
type	string	Specific document type
subtype	string	Sub-type of the document
isDoubleSided	boolean	Indicates if the document has two sides
hasNFC	boolean	Indicates if the document has NFC capability
year	string	Year of document issuance or version
countryCode	string	Country code (ISO 3166-1 alpha-2)
countryName	string	Full country name
stateCode	string	State or region code
stateName	string	Full state or region name
sides	array of SideClassification	Classification details of the document sides

Sample Data

{
  "ids": ["1234"],
  "category": "Passport",
  "type": "National ID",
  "subtype": "Standard",
  "isDoubleSided": true,
  "hasNFC": false,
  "year": "2020",
  "countryCode": "GB",
  "countryName": "United Kingdom",
  "stateCode": "ENG",
  "stateName": "England",
  "sides": [
    {
      "side": "front",
      "id": "front-id",
      "documentQuality": "good",
      "documentQualityScore": 95
    }
  ]
}

SideClassification

Property	Type	Description
side	string	Specifies which side of the document (e.g., “front”, “back”)
id	string	Unique identifier for the document side
documentQuality	string	Quality assessment of the document side (e.g., “good”, “poor”)
documentQualityScore	number	Score indicating document quality (e.g., 0-100)

Sample Data

{
  "side": "front",
  "id": "front-id",
  "documentQuality": "good",
  "documentQualityScore": 95
}

Rectangle

Property	Type	Description
x	number	X-coordinate of the bounding box
y	number	Y-coordinate of the bounding box
width	number	Width of the bounding box
height	number	Height of the bounding box

Sample Data

{
  "x": 100,
  "y": 50,
  "width": 300,
  "height": 100
}

RegionOfInterest

Property	Type	Description
boundingBox	Rectangle	Bounding box defining the region of interest
side	string	Specifies which side of the document (e.g., “front”, “back”)
spectrum	string	Spectrum type (e.g., “visible”, “infrared”)
imageId	string	Identifier for the associated image

Sample Data

{
  "boundingBox": {
    "x": 100,
    "y": 50,
    "width": 300,
    "height": 100
  },
  "side": "front",
  "spectrum": "visible",
  "imageId": "img-001"
}

DocumentField

Property	Type	Description
label	string	Name of the field (e.g., “Document Number”, “Full Name”)
value	string	Extracted value of the field
source	string	Source of extraction (e.g., “OCR”, “MRZ”)
isNonLatin	boolean	Indicates if the value contains non-Latin characters
regionOfInterest	RegionOfInterest	Bounding box defining the field’s location

Sample Data

{
  "label": "Document Number",
  "value": "1234567890",
  "source": "OCR",
  "isNonLatin": false,
  "regionOfInterest": {
    "boundingBox": {
      "x": 100,
      "y": 50,
      "width": 300,
      "height": 100
    },
    "side": "front",
    "spectrum": "visible",
    "imageId": "img-001"
  }
}

ExtractedField

Property	Type	Description
label	string	Name of the extracted field (e.g., “Full Name”)
details	array of DocumentField	Detailed extracted data for this field

Sample Data

{
  "label": "Full Name",
  "details": [
    {
      "label": "First Name",
      "value": "David",
      "source": "OCR"
    },
    {
      "label": "Last Name",
      "value": "Jones",
      "source": "OCR"
    }
  ]
}

Country

Property	Type	Description
Country	string	ISO 3166-1 alpha-2 country code

Sample Data

"GB"

Identity

Property	Type	Description
firstName	string	Given name of the individual
lastName	string	Family name of the individual
dateOfBirth	string (date)	Date of birth in `YYYY-MM-DD` format
gender	string	Gender of the individual
nationality	string	Nationality (ISO 3166-1 alpha-2 country code)

Sample Data

{
  "firstName": "David",
  "lastName": "Jones",
  "dateOfBirth": "1985-01-01",
  "gender": "Male",
  "nationality": "GB"
}

ExtractedImage

Property	Type	Description
label	string	Name or type of the extracted image
side	string	Specifies which side of the document (e.g., “front”, “back”)
imageID	string	Unique identifier for the extracted image

Sample Data

{
  "label": "Face Photo",
  "side": "front",
  "imageID": "img-12345"
}

DocumentExtractionInfoV1

Property	Type	Description
aggregatedFields	array of DocumentField	List of extracted document fields with aggregated data
extractedFields	array of ExtractedField	List of individual extracted fields with details
extractedImages	array of ExtractedImage	List of extracted images from the document

Sample Data

{
  "aggregatedFields": [
    {
      "label": "Document Number",
      "value": "1234567890",
      "source": "OCR",
      "isNonLatin": false,
      "regionOfInterest": {
        "boundingBox": {
          "x": 100,
          "y": 50,
          "width": 300,
          "height": 100
        },
        "side": "front",
        "spectrum": "visible",
        "imageId": "img-001"
      }
    }
  ],
  "extractedFields": [
    {
      "label": "Full Name",
      "details": [
        {
          "label": "First Name",
          "value": "David",
          "source": "OCR"
        },
        {
          "label": "Last Name",
          "value": "Jones",
          "source": "OCR"
        }
      ]
    }
  ],
  "extractedImages": [
    {
      "label": "Face Photo",
      "side": "front",
      "imageID": "img-12345"
    }
  ]
}

DocumentValidationCheck

Property	Type	Description
name	string	Name of the validation check (e.g., “MRZ Check”)
title	string	Detailed title of the validation check
info	string	Description of the validation check
validationResult	string	Result of the validation (e.g., “Passed”, “Failed”)
resultInfo	string	Additional details about the validation result
weight	string	Weight or priority of the validation check
regionOfInterests	array of RegionOfInterest	List of regions of interest related to the validation check
type	string	Type of validation check

Sample Data

{
  "name": "MRZ Check",
  "title": "Machine Readable Zone Validation",
  "info": "Verifies MRZ matches document details",
  "validationResult": "Passed",
  "resultInfo": "Valid MRZ format",
  "weight": "High",
  "regionOfInterests": [
    {
      "boundingBox": {
        "x": 50,
        "y": 200,
        "width": 250,
        "height": 50
      },
      "side": "back",
      "spectrum": "visible",
      "imageId": "img-002"
    }
  ],
  "type": "Security Check"
}

DocumentValidationInfoV1

Property	Type	Description
validationChecks	array of DocumentValidationCheck	List of individual validation checks performed on the document
aggregatedValidationChecks	array of DocumentValidationCheck	Aggregated results of validation checks

Sample Data

{
  "validationChecks": [
    {
      "name": "MRZ Check",
      "title": "Machine Readable Zone Validation",
      "info": "Verifies MRZ matches document details",
      "validationResult": "Passed",
      "resultInfo": "Valid MRZ format",
      "weight": "High",
      "regionOfInterests": [
        {
          "boundingBox": {
            "x": 50,
            "y": 200,
            "width": 250,
            "height": 50
          },
          "side": "back",
          "spectrum": "visible",
          "imageId": "img-002"
        }
      ],
      "type": "Security Check"
    }
  ],
  "aggregatedValidationChecks": [
    {
      "name": "Security Features Check",
      "title": "Security Features Validation",
      "info": "Ensures embedded security features are valid",
      "validationResult": "Failed",
      "resultInfo": "Hologram not detected",
      "weight": "Medium",
      "regionOfInterests": [
        {
          "boundingBox": {
            "x": 100,
            "y": 150,
            "width": 200,
            "height": 100
          },
          "side": "front",
          "spectrum": "infrared",
          "imageId": "img-003"
        }
      ],
      "type": "Forgery Check"
    }
  ]
}

CommonBiometrics

Property	Type	Description
id	string (nullable)	Unique identifier for the biometric data
type	string (nullable)	Type of biometric data

Sample Data

{
  "id": "bio-123456",
  "type": "face-recognition"
}

FaceImageBiometricsCapture

Extends: CommonBiometrics

Property	Type	Description
id	string (nullable)	Unique identifier for the biometric capture
faceImage	Base64StringOrImageId	Face image in Base64 format or an image ID reference

Sample Data

{
  "id": "face-bio-789123",
  "type": "face-recognition",
  "faceImage": "/images/face-image-001"
}

FaceImageCompareBiometricsCapture

Extends: CommonBiometrics

Property	Type	Description
id	string (nullable)	Unique identifier for the biometric comparison
face1Image	Base64StringOrImageId	First face image in Base64 format or an image ID reference
face2Image	Base64StringOrImageId	Second face image in Base64 format or an image ID reference

Sample Data

{
  "id": "face-compare-456789",
  "type": "face-recognition",
  "face1Image": "/images/face1-image-002",
  "face2Image": "/images/face2-image-003"
}

Introduction

Customer Journey

​Understand the context object and schema

​What is the context object?

​Where does the schema come from?

​Why is the schema important?

​Key objects in the context schema

​How to use the table below

​Person

​Sample Data

​Supporting Schemas

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

​IdentityDocument

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​Sample Data

​FaceImageCompareBiometricsCapture

​Sample Data

Understand the context object and schema

What is the context object?

Where does the schema come from?

Why is the schema important?

Key objects in the context schema

How to use the table below

Person

Sample Data

Supporting Schemas

IdentityDocument

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

Sample Data

FaceImageCompareBiometricsCapture

Sample Data