> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  This page documents the **input schema** for API requests. For information about API response data, see the [Response advice schema](/docs/go-v2/api-reference/response-schema) page.
</Note>

### 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.

<Note>
  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.
</Note>

### 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](#namesobject)         | Alternative names used by the person              |
| relatedPersons    | [array of RelatedPerson](#relatedperson)     | Related persons with relationship type            |
| dateOfBirth       | [Date](#date)                                | Birth date of the individual                      |
| gender            | string                                       | Gender of the individual                          |
| currentAddress    | [Address](#address)                          | Current residence of the individual               |
| previousAddresses | [array of PreviousAddress](#previousaddress) | Past residences with date range                   |
| placeOfBirth      | [Address](#address)                          | Birthplace of the individual                      |
| documents         | [array of Documents](#documents)             | Identity documents with type, number, and country |
| phones            | [array of Phones](#phones)                   | Contact numbers                                   |
| emails            | [array of Emails](#emails)                   | Email addresses                                   |
| accounts          | [array of Accounts](#accounts)               | Bank accounts for verification                    |
| socials           | array of Socials                             | Social media accounts                             |

### Sample data

```json theme={null}
{
  "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": "+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, 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)     | Address object                                         |
| dateRange | [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

```json theme={null}
[
  {
    "type": "mobile",
    "number": "+44 207 4281250"
  }
]
```

#### 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](#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

```json theme={null}
[
  {
    "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                    | `"person.name@domain.com"` |

##### Sample data

```json theme={null}
[
  {
    "type": "home",
    "email": "person.name@domain.com"
  }
]
```

#### 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

```json theme={null}
[
  {
    "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
"2019-01-04T14:38:25Z"
```

#### TimeRange

| Property | Type                  | Description     |
| -------- | --------------------- | --------------- |
| start    | [DateTime](#datetime) | Start timestamp |
| end      | [DateTime](#datetime) | End timestamp   |

##### Sample data

```json theme={null}
{
  "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

```json theme={null}
"2000-01-01"
```

#### DateRange

| Property | Type          | Description |
| -------- | ------------- | ----------- |
| fromDate | [Date](#date) | Start date  |
| toDate   | [Date](#date) | End date    |

##### Sample data

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "status": 404,
  "message": "Not Found Error, validate resource Id",
  "error": "not-found-error"
}
```

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

##### Sample data

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
"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

```json theme={null}
{
  "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](#base64stringorimageid) | Face image in Base64 format or an image ID reference |

### Sample data

```json theme={null}
{
  "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](#base64stringorimageid) | First face image in Base64 format or an image ID reference  |
| face2Image | [Base64StringOrImageId](#base64stringorimageid) | Second face image in Base64 format or an image ID reference |

### Sample data

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