User data input schema

This section contains an explanation of the schema for passing customer data

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.

This page documents the input schema for API requests. For information about API response data, see the Response advice schema page.

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.

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 Array: Simple document identifiers (type, number, country) used for data verification checks in context.subject.documents.
• IdentityDocument Object: Full document verification schema including images, classification, and validation 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

This schema represents the structure of context.subject or context.subject.identity depending on your journey configuration.

Property	Type	Description
uid	string	Unique identifier for the subject
title	string	Title of the individual
firstName	string	Given name of the individual
middleNames	array of strings	Any additional registered names
lastNames	array of strings	Family names of the individual
lastNamesAtBirth	array of strings	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	string	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
documents	array of Documents	Identity documents with type, number, and country
phones	array of Phones	Contact numbers
emails	array of Emails	Email addresses
accounts	array of Accounts	Bank accounts for verification
socials	array of Socials	Social media accounts

Sample data

{
  "uid": "user-12345",
  "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"
  },
  "documents": [
    {
      "type": "CPF Number",
      "number": "87565779318",
      "country": "BRA"
    }
  ],
  "phones": [
    {
      "type": "mobile",
      "number": "[phone]"
    }
  ],
  "emails": [
    {
      "type": "work",
      "email": "[e-mail]"
    }
  ],
  "socials": [
    {
      "type": "LinkedIn",
      "identity": "davidjones123"
    }
  ]
}

Supporting Schemas

RelatedPerson

Property	Type	Description
relationship	string	Relationship type, for example, "mother", "father", "maternalGrandFather", etc.)
title	string	Title of the related person
firstName	string	Given name of the related person
middleNames	array of strings	Additional registered names of the related person
lastNames	array of strings	Family names of the related person
lastNamesAtBirth	array of strings	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	"[phone]"

Sample data

[
  {
    "type": "mobile",
    "number": "[phone]"
  }
]

Documents

This is a simplified document schema used in context.subject.documents for data verification checks. For full document verification with images and classification, see the IdentityDocument schema below.

Property	Type	Description	Example
type	string	Type of document, for example, Passport, and CPF Number	"CPF Number"
number	string	The document number	"87565779318"
country	string	Country code (ISO 3166-1 alpha-2 or alpha-3)	"BRA"

Sample data

[
  {
    "type": "CPF Number",
    "number": "87565779318",
    "country": "BRA"
  }
]

Emails

Property	Type	Description	Example
type	string	Type of email (home, work, etc.)	"home"
email	string	Email address	"[e-mail]"

Sample data

[
  {
    "type": "home",
    "email": "[e-mail]"
  }
]

Accounts

Property	Type	Description	Example
type	string	Type of account	"Bank Account"
accountNumber	string	Account number	"12345678"
sortCode	string	Sort code (UK)	"12-34-56"
routingNumber	string	Routing number (US)	"021000021"
iban	string	International Bank Account Number	"DE89370400440532013000"
bic	string	Bank Identifier Code	"COBADEFFXXX"
accountHolderName	string	Name of the account holder	"Jane Doe"
bankName	string	Name of the bank	"Example Bank Ltd"
country	string	Country code (ISO 3166-1 alpha-2)	"GB"
accountType	string	Type of bank account (current, savings, etc.)	"current"

Sample data

[
  {
    "type": "Bank Account",
    "accountNumber": "12345678",
    "sortCode": "12-34-56",
    "accountHolderName": "Jane Doe",
    "bankName": "Example Bank Ltd",
    "country": "GB",
    "accountType": "current"
  }
]

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"
building	string	Building number (alternative)	"792"
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"
administrativeArea	string	State or administrative region	"RJ"
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"
}

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

DateTime

An ISO 8601 timestamp, with no optional bits:

1. Hyphens MUST be used to separate the date components.
2. Day and month should be 2 digits.
3. Colons MUST be used to separate the time components.
4. Timestamps MUST NOT contain milliseconds.
5. 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

Typical error response format returned by a GBG API.

Property	Type	Description
status	int	The HTTP status code, for example, 404
message	string	A human-readable message giving more detail about the error
error	string	message describing the error for troubleshooting purposes

Sample data

{
  "status": 404,
  "message": "Not Found Error, validate resource Id",
  "error": "not-found-error"
}

Some error responses may also include additional information about the error, such as API path or timestamp.

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, for example, passport and 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"
}