> ## 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.
# FAQ
> Answers to common GBG GO questions: account access, journey concepts, API integration, submitting data, and troubleshooting.
## Account and access
If you have forgotten your password:
1. Go to the GBG GO sign-in page.
2. Click **Forgot your password?** on the login screen.
3. Check your email for a recovery code and enter it in the recovery code field.
4. Enter a new password and confirm it.
5. Click **Change Password** to save your new password.
GBG GO provides two separate environments:
* **Preview environment**: A test environment where you can validate journeys before deploying them to production. Use this to test API calls, verify journey behaviour, and confirm that modules are configured correctly.
* **Production environment**: The live environment where published journeys are used by real customers.
**To publish a journey to the preview environment:**
1. Open your journey in the Journey builder.
2. Click **Publish to Preview**.
3. A confirmation message appears: "Delivery deployed successfully".
4. Click **Dashboard**, where you can see the environment label (Preview), version number, resource ID, last published date, and the auto-generated schema.
To access preview data in the Investigation portal:
1. Navigate to **Investigation**.
2. Click the **Preview Environment** tab.
The preview environment uses a separate resource ID from production. When testing your API integration, use the preview resource ID from the Dashboard. Once testing is complete, publish the journey to production to generate a production resource ID.
## Core concepts
These are the core building blocks of the GBG GO platform:
* **Journey**: A journey is a structured workflow that guides an end user through verification steps such as identity checks, document processing, and fraud screening.
* **Module**: A module is a functional component within a journey that performs a specific verification task. Examples include **Document Classification**, **Document Authentication**, **Data Verification**, **Age Verification**, and **Facematch**. Each module can have one or more *variants*, which are different configurations tailored to specific regions, compliance rules, or business requirements, for example, "US Data Verification."
* **Capability**: Capabilities are the underlying services that modules use to perform their tasks. For example, the Document Authentication module relies on the Document Authentication capability, which provides the core logic for verifying document authenticity.
* **Task**: A task is an action a user must complete within a journey, such as providing identity details, uploading a document, or performing biometric verification. When you retrieve tasks, the response describes which tasks are assigned to the journey instance. Each task has a unique `taskId` and moves through the **Assigned**, **In Progress**, and **Completed** stages as the journey progresses.
* **Evaluation**: An evaluation is a decision-making step in the journey where the platform determines an outcome, such as accept, reject, or refer for manual review, based on the results of the preceding verification modules.
A **resource ID** identifies a specific published version of a journey. When you publish a journey in GBG GO, the system assigns it a resource ID. You include this ID in the journey start request to tell the API which journey to run. To always use the most recently published version, append `@latest` to the resource ID (for example, `your-resource-id@latest`). To pin your integration to a specific version, use the fixed resource ID without `@latest`.
An **instance ID** identifies a single execution of that journey. When you start a journey, the API creates a journey instance and returns a unique `instanceId` in the response. You use this instance ID in subsequent API calls.
In the v1 API, prefill journeys can run in either synchronous or asynchronous mode.
* **Synchronous (default)**: When you call `/journey/start` in prefill mode, the response returns only after all modules have finished processing. This is convenient for short-running journeys but can cause timeout issues for long-running verification flows.
* **Asynchronous**: Set `"async": true` inside the `config` object on the `/journey/start` request. The call returns an `instanceId` immediately and processing happens in the background. Use this mode to avoid timeouts.
```json JSON theme={null}
{
"resourceId": "your-resource-id@latest",
"context": {
"config": { "async": true },
"subject": {
"identity": { "firstName": "Jane", "lastNames": ["Doe"] }
}
}
}
```
To track progress in async mode, poll the [`/journey/state/fetch`](/docs/go-v1/api-reference/endpoint/fetch-journey-state) endpoint until the status changes from `InProgress` to `Completed` or `Failed`. The recommended approach is to poll at a base interval of 10 seconds with backoff on errors.
In synchronous prefill execution, if module processing fails to complete, a `5xx` error is returned.
## Starting a journey
The `config` object is included inside `context` when you start a journey. It controls how the journey is executed.
The primary value you can set is `async`, which determines whether the journey runs in asynchronous mode:
* `"async": true`: The `/journey/start` call returns the `instanceId` immediately and module processing happens in the background. Use this for long-running prefill journeys to avoid timeouts.
* `"async": false` (or omitted): The journey runs synchronously. The response returns only after all modules have finished processing.
Example with async prefill:
```json JSON theme={null}
{
"resourceId": "your-resource-id@latest",
"context": {
"config": { "async": true },
"subject": {
"identity": {
"firstName": "Jane",
"lastNames": ["Doe"],
"dateOfBirth": "1992-10-01"
}
}
}
}
```
Example for non-prefill mode (no `config` needed):
```json JSON theme={null}
{
"resourceId": "your-resource-id@latest",
"context": {
"subject": {
"documents": [],
"biometrics": []
}
}
}
```
The `uid` field is an optional string inside `context.subject` that allows you to associate a journey instance with a specific user in your system. It acts as a correlation identifier, linking the GBG GO journey to an existing customer or user record on your side.
For example, if your system assigns each customer a unique ID like `user-12345`, you can pass it as the `uid` when starting a journey:
```json JSON theme={null}
{
"resourceId": "your-resource-id@latest",
"context": {
"subject": {
"uid": "user-12345"
}
}
}
```
This is useful for:
* **Traceability**: Matching journey results back to the correct customer record in your system.
* **Debugging**: Identifying which user a journey instance belongs to when investigating issues.
* **Reporting**: Correlating GBG GO verification outcomes with your internal user data.
The `uid` field is not required and does not affect journey processing. If you do not need to correlate journeys with an external system, you can omit it.
## Submitting data
In the v1 API, documents are submitted as part of a task data submission to the [`/journey/task/update`](/docs/go-v1/api-reference/endpoint/submit-task-data) endpoint. Each document object includes a base64-encoded image for each side and a type field, placed inside `context.subject.documents`.
**Example:** Submitting the front of a primary document:
```json JSON theme={null}
{
"intent": "Complete",
"instanceId": "your-instance-id",
"taskId": "your-task-id",
"context": {
"subject": {
"documents": [
{
"side1Image": "",
"side2Image": "",
"type": "Primary"
}
]
}
}
}
```
**Field reference:**
| Field | Description |
| ------------ | --------------------------------------------------------------------------------------------- |
| `side1Image` | Base64-encoded image of the front of the document. |
| `side2Image` | Base64-encoded image of the back of the document. Leave as an empty string if not applicable. |
| `type` | The document type. Use `"Primary"` for the main identity document. |
### Submitting a selfie
Biometric data such as a selfie is submitted inside `context.subject.biometrics` on the same `/journey/task/update` call:
```json theme={null}
{
"intent": "Complete",
"instanceId": "your-instance-id",
"taskId": "your-task-id",
"context": {
"subject": {
"biometrics": [
{
"selfieImage": ""
}
]
}
}
}
```
Documents and biometrics must be placed inside `context.subject`. Placing them outside `subject` causes the request to fail. Use `"intent": "Complete"` to mark the task as finished.
Identity data is submitted inside `context.subject.identity` as part of a task data submission to the [`/journey/task/update`](/docs/go-v1/api-reference/endpoint/submit-task-data) endpoint. You only need to include the fields relevant to the task's schema.
### Submitting a Social Security Number (SSN)
SSN is submitted as an entry in the `idNumbers` array with a `type` of `"ssn"`:
```json JSON theme={null}
{
"intent": "Complete",
"instanceId": "your-instance-id",
"taskId": "your-task-id",
"context": {
"subject": {
"identity": {
"idNumbers": [
{
"idNumber": "123-45-6789",
"type": "ssn"
}
]
}
}
}
}
```
### Submitting date of birth only
The response below shows how to submit just the date of birth if that's the only required field for your task.
```json JSON theme={null}
{
"intent": "Complete",
"instanceId": "your-instance-id",
"taskId": "your-task-id",
"context": {
"subject": {
"identity": {
"dateOfBirth": "1990-01-01"
}
}
}
}
```
### Submitting partial identity data in prefill mode
In prefill mode, you can provide a subset of the required identity fields when you start the journey. Any fields you don't provide are collected from the end user through tasks. After starting the journey, call [Retrieve tasks](/docs/go-v1/developer-integration/execute-customer-journeys/retrieve-tasks-step) to see which tasks still need to be completed, and submit the remaining data through `/journey/task/update`.
Always validate your input against the task schema before sending. If the data is missing required fields or uses the wrong structure, the API returns a validation error.
## Errors and troubleshooting
To authenticate, send a `POST` request to the token endpoint:
```json JSON theme={null}
https://api.auth.gbgplc.com/as/token.oauth2
```
The request must be sent with the following parameters:
| Parameter | Description |
| --------------- | ---------------------------- |
| `grant_type` | Set to `client_credentials`. |
| `client_id` | The client ID. |
| `client_secret` | The client secret. |
| `scope` | Set to `gbg.token`. |
Example request:
```bash BASH theme={null}
curl --request POST \
--url https://api.auth.gbgplc.com/as/token.oauth2 \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials' \
--data 'client_id=your-client-id' \
--data 'client_secret=your-client-secret' \
--data 'scope=gbg.token'
```
A successful response returns:
```json theme={null}
{
"access_token": "your-access-token",
"token_type": "Bearer",
"expires_in": 3600
}
```
Include the token in the `Authorization` header of subsequent API request as `Bearer your-access-token`. Store the token securely and refresh it before it expires.
You create API clients yourself in the **Clients** tab of the Account management portal, where you generate the client ID and client secret used to authenticate. For details, see **Manage API clients** in Account management.
You can access detailed failure reasons in two ways:
* Through the v1 API error response
* Through the **Investigation** portal.
### v1 API error responses
The v1 API returns structured error objects that include a machine-readable error code, a description of the problem, and a recommended action. Each error specifies where the issue originated, making it easier to diagnose failures programmatically.
```json theme={null}
{
"errors": [
{
"code": "4002",
"name": "MISSING_FIELD",
"location": "Body",
"problem": "problem description goes here",
"action": "action to resolve the issue goes here"
}
]
}
```
| Field | Description |
| ---------- | -------------------------------------------------------------------------- |
| `code` | Numeric error code (returned as a string). |
| `name` | Machine-readable error identifier (for example, `MISSING_FIELD`). |
| `location` | Where the error originated: `Body`, `Authorization`, `Path`, or `Service`. |
| `problem` | A description of what went wrong. |
| `action` | What you should do to resolve the error. |
Every API response also includes an `X-Request-ID` header. Include this value when contacting GBG support. It correlates your request with server-side logs for faster troubleshooting.
### Investigation portal
For document-specific verification failures, the **Investigation** portal provides the most detailed view. To access granular failure reasons:
1. Log in to the GBG GO platform and navigate to the **Investigation** section.
2. Click the **Session ID** of the session you want to review. This opens the session detail view, which shows an overview of the session.
3. Navigate to the **Processing** tab to see each module's outcome, for example, Match, No Match, or Error.
4. Expand any module section to see a breakdown of individual data point matches.
5. Click **More details** to open the module detail view. The available tabs vary by module type.
6. Check the **Raw Response** tab for the complete response from the verification provider, which contains the module errors and reasons.
## Investigation
You can review everything a customer submitted from the **Investigation** portal in GBG GO.
1. Sign in to GBG GO and click **Investigation** in the left navigation menu.
2. Click the **Session ID** of the session you want to review. The session details page opens.
3. Use the following tabs to view different parts of the submitted data:
| Tab | What you see |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Processing** | The modules that ran during the journey, their outcomes (for example, *Match*, *Extraction Successful*, *Low risk*), and the execution sequence. Expand any module to see the individual data point matches that produced the outcome. |
| **User Data** | Personal information, contact details, and identification data the customer provided. |
| **Documents & Biometrics** | Images of submitted identity documents and the selfie or facial recognition data, plus the verification results for each. |
| **Audit Log** | A chronological history of actions taken on the session, including any decision changes and PDF exports. |
For a deeper look at any module, click the down carrot at the right end of the module and select **More details**. The available sub-tabs (for example, *Results*, *Extracted Images*, *Checks*, *Raw Response*, *Outcome Rules*) vary by module type. The **Raw Response** tab contains the full JSON response from the verification provider, which is the most detailed view of what was returned.
See [View details of a customer session](/docs/go-v1/platform/investigate/view-customer-details) for a full walkthrough.
The Investigation dashboard lists every verification session for the selected environment and region. To narrow it down:
**Switch environment or region first.** If you can't find the session you expect, check that you're looking at the right environment (**Production** or **Preview** tab at the top-left) and the right region (selector at the top-right). Sessions only appear in the environment and region they were processed in.
**Filter the session list:**
1. Click **Add Filter**.
2. Select a filter (for example, **Name**, **Email**, **Trust Score**, **Decision**) and click **Add Filter**.
3. Apply additional filters as needed — the number of applied filters appears next to the filter button.
4. Click **Apply Filter**. Use **Clear All** to reset.
**Sort the session list:**
1. Hover over a column title and click the three dots that appear.
2. Choose **Sort by ASC** or **Sort by DESC**. You can sort by Session ID, Name, Decision, Started date, and other columns.
**Show or hide columns:** From the same three-dot menu on any column, choose **Hide column** or **Manage columns** to control which columns appear on the dashboard.
Sessions are subject to your organization's data retention policy. Sessions older than the retention period may no longer appear on the dashboard.
You can override an automated decision from either the session details page or the main Investigation dashboard.
**From the session details page (recommended when you need full context):**
1. Click the **Session ID** of the session.
2. Review the session details, including processing modules, user data, and documents.
3. Select a new decision from the list. The default options are:
* **Decision: Accept**
* **Decision: Manual review**
* **Decision: Reject**
4. (Optional) Add a note in the **Note** field explaining the reason for the change.
5. Click **Change decision** to confirm.
**From the main dashboard (useful for high-volume reviews):**
1. Select the checkbox next to the session.
2. Click **Change Decision**.
3. Select a new decision, optionally add a note, and click **Change decision**.
Every decision change is recorded in the session's **Audit Log** tab, including who made the change, when it happened, and any note you added.
You can't change a decision while a journey is still in progress (no evaluation yet). Wait for processing to finish before overriding the decision.
See [Change decisions](/docs/go-v1/platform/investigate/change-decisions) for the full guide.
You can export a complete customer session as a PDF directly from the Investigation portal. The exported PDF includes all session data: processing modules, user data, documents, biometrics, checks, and audit log entries.
To export a session:
1. Sign in to GBG GO and click **Investigation**.
2. Click the **Session ID** of the session you want to export.
3. Click **Export** in the top-right corner of the session details page. The **Export session** dialog appears.
4. Click **Export to PDF**. The file downloads to your device automatically.
Every PDF export is recorded in the session's **Audit Log** tab with a timestamp and the user who triggered it, which is useful for compliance and audit trails.
See [Export customer session](/docs/go-v1/platform/investigate/session-download-pdf) for more details.
The audit log records a chronological history of actions taken during a verification session. You can view the audit log for any session in the Investigation portal by navigating to the **Audit Log** tab within a session's detail page.
The audit log displays the following information for each recorded action:
| Column | Description |
| ------------- | ------------------------------------------------------------------------ |
| Date and time | When the action occurred. |
| User | Who performed the action. |
| Action | The specific action taken for example, changing a verification decision. |
| Data | Additional details about the action. |
For example, if a reviewer changes a session's decision from rejected to accepted, the audit log records who made the change, when it happened, and any notes associated with it.
You can sort the audit log by date to review events in chronological order, and use the page navigation controls at the bottom to move between pages of results.
## Contact
If you can't find the answer to your question, see [Troubleshooting and support](/docs/go-v1/get-started/troubleshooting-and-support) for ways to get in touch with the GBG team.