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

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	`^\d4-\d2-\d2T\d2:\d2:\d2(([+-]\d2:\d2)	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"
}

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

FaceImageBiometricsCapture

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

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

​IdentityDocument

​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

FaceImageCompareBiometricsCapture

Sample Data