Key concepts

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.

Understanding how the GBG GO platform works will help you create, manage, and integrate customer journeys. GBG GO supports two integration methods:

• API-first integration: You build the complete user interface and use GBG GO APIs to submit verification data and retrieve results. This gives you full control over the user experience. To learn more, refer to API-first integration.
• Hosted journeys: The GBG GO platform generates and hosts the user interface. You make a single API call to start a journey and receive a secure URL where end users complete verification. To learn more, refer to Hosted journeys.

​

Customer journeys and workflow

A customer journey is a structured process that guides a user through steps such as identity verification, document processing, and approvals.

• Business users create and configure customer journeys in the GBG GO platform. They define workflows, add verification steps, and publish journeys.
• Developers integrate with the API to start journeys, fetch interactions, and submit verification data.

​

Modules

A module is a functional component within a customer journey that performs a specific task, such as identity verification, document authentication, or fraud detection. Modules are the building blocks of journeys in GBG GO — you combine them to create comprehensive identity workflows tailored to your business and compliance requirements. Each module produces results known as outcomes, which can be configured to drive decisions later in the journey. Examples of modules in GO include Age Verification and Document Authentication. To browse all available modules, see the Modules overview.

​

Outcomes and decisions

In GBG GO, outcomes typically refer to module results while decisions refer to evaluation results. See Glossary of terms for more details. Outcomes and decisions are evaluated in order from top to bottom. When a condition is met, that result is returned and processing stops. For example, in a NameMatch module, if customer names match correctly, the system immediately returns the IsNameMatch outcome. All remaining configured outcomes are skipped.

​

Journey instance

When a journey starts, the system creates a journey instance, which represents an active execution of a customer journey. Each instance is assigned a unique instanceId, which you use to track progress, fetch interactions, and submit verification data.

​

Partial prefill mode and non-prefill mode

When starting a journey using GO APIs, you can choose between two modes:

• Partial prefill mode: You remove specific domain elements you already have from the Interaction Group panel and send that data upfront in the context.subject object when starting the journey. The remaining domain elements are left in the interaction group for the end user to complete during the journey.
• Non-prefill mode: starts a journey without customer data. You send an empty context object, and customers provide required details through interactions later.

​

Linear and adaptive journey processing

Journeys can be processed in two ways: linear or adaptive.

• Linear processing: The journey follows a fixed sequence of steps. Each task must be completed in order before moving to the next.
• Adaptive processing: The journey dynamically adjusts based on customer data and verification results. Tasks may be skipped or added depending on the context. Data is collected sequentially based on the journey stage, allowing for a more tailored verification process.

​

Resource ID and journey versions

A resource ID identifies a specific journey version. When a journey is published, it receives a unique resource ID. To start a journey, you provide this ID in the request. If you want to start the most recent published version, append @latest, for example, your-resource-id@latest. If your integration requires a specific version, use the fixed resource ID instead of @latest.

​

Interactions and domain elements

In v2, data collection is driven by interactions. Each interaction defines what information the end user must provide at a given point in the journey.

​

Interaction

An interaction is a unit of data collection within a journey. When you fetch the current interaction, the API returns:

• The interaction ID and UI layout definition.
• The domain elements the interaction collects (collects[]).
• The domain elements not yet submitted (outstanding[]).

You use this response to build or render the appropriate form for the end user, then submit the collected data.

​

Domain elements

A domain element is a discrete unit of identity data, for example, FullName, DateOfBirth, or PrimaryDocument. Each domain element has a defined schema that specifies its required fields and expected data structure. When submitting interaction data, you include the domain element identifiers in the participants array and provide the corresponding data in context.subject.

​

Interaction loop

After starting a journey, you repeatedly:

1. Fetch the current interaction to discover what data is required.
2. Collect the data from the end user.
3. Submit the interaction data.
4. Repeat until journey.status is no longer InProgress.

If a journey is running in Partial prefill mode, you must retrieve the schema from the Journey Dashboard in the GBG GO platform before starting the journey. The schema tells you:

• Which fields must be included.
• What data types are expected (string, array, object).
• How identity information should be structured.

To retrieve and understand a schema, see the Retrieve the schema for prefill mode section.

​

Identity and user data in journeys

A context object holds structured user data, including:

• Personal details: First name, last name, date of birth.
• Contact information: Email addresses, phone numbers.
• Address details: Current and previous addresses.
• Government-issued IDs: Passport numbers, Social Security Numbers.

If you start a journey in Prefill mode, you must include a correctly structured context object. The system uses this data to auto-complete tasks that match the provided information. If any required fields are missing or invalid, pending tasks will be created.

​

User roles in GBG GO

There are two main user roles in the platform:

• Business users design and configure customer journeys in the GBG GO platform. They define workflows, add verification modules, and publish journeys.
• Developers integrate with the API to start journeys, fetch interactions, and submit verification data.

Business users focus on creating and managing customer journeys, while developers work on automation and data handling through API calls.

​

Authentication and security

​

Access tokens

To interact with the API, you must authenticate using an access token. This temporary credential is required for every API request.

• Access tokens must be included in the Authorization header.
• They expire after a set period and must be refreshed when they become invalid.

To obtain an access token, follow the Authentication guide.

​

Device connection

Some journeys require linking a customer’s session to a device. In such cases, the API provides a connection secret, allowing the device to:

• Authenticate without requiring repeated logins.
• Refresh its session securely.

​

Journey state and tracking

A journey state indicates the current status of an active journey instance. The most common states include:

• In Progress: The journey is active, and tasks are pending.
• Completed: The journey has been fully processed.
• Pending Input: The journey is waiting for user action.

To monitor journey progress, retrieve the journey state using the API.

​

Hosted journey concepts

The concepts below apply specifically to hosted journeys, where the GBG GO platform generates and hosts the end-user interface.

​

Hosted journeys

A Hosted journey is a verification journey where the GBG GO platform generates and hosts the user interface that end users interact with. Instead of building a custom frontend application, you configure your journey in the Journey Designer. The GO platform then creates the screens needed to collect information from end users. A hosted journey combines three elements:

• Processing modules: These perform verification checks such as identity verification, document authentication, and fraud detection.
• Interaction nodes: These present screens to end users for information collection.
• Flow control: These determine which screens end users see based on verification outcomes.

The platform manages the relationship between these elements. When you add or remove modules, the platform updates the interaction nodes to reflect the new data requirements.

​

Domain elements

A domain element is a specific piece of information that a verification module requires to perform its checks. Domain elements represent the fundamental data units of the verification process. Examples of domain elements include:

• Personal identity information such as first name, last name, and date of birth
• Contact details such as email address and phone number
• Document data such as identity document images and document numbers
• Biometric data such as selfie images for liveness and face match verification

Each module in a journey declares which domain elements it needs as input and which it produces as output. The platform uses these declarations to determine what information to collect from end users and when to collect it. If two modules require the same domain element, then the platform collects it once and shares it across both modules.

​

Hosted pages

Hosted pages are the user-facing web interfaces that the GBG GO platform generates and serves for hosted journeys. When you enable hosted pages, the platform provides:

• Information collection forms with field types, validation, and error handling appropriate to each domain element
• Biometric capture for liveness detection and face match verification
• Responsive design that adapts to different screen sizes and devices
• Document capture interfaces integrated with GBG document verification SDK for identity document scanning

​

How the platform generates screens

When you enable hosted pages, the platform examines each module in your journey flow and identifies the domain elements that module requires as input. It then compiles a de-duplicated list of all required domain elements across the journey. From this list, the platform creates interaction nodes containing screens with fields for collecting the necessary information from end users. The platform organises fields based on the order of modules in the flow and the priority of fields within each module. Required fields appear before recommended fields. When you modify the journey flow, the platform automatically updates the screens to match.

​

Pages, cards, and screens

The hosted interface is organised into a hierarchy that groups related information logically:

• Page: A single view in the user interface that collects a focused set of information and contains one or more cards. End users navigate between pages using Next and Back controls.
• Card: A visual grouping of input fields within a page, typically collecting information for a single domain element or a set of closely related domain elements.
• Screen: The complete view that the end user sees at any point, including the current page, navigation controls, progress indicators, and branding elements.

​

Interaction groups

An interaction group is a collection of interaction nodes within a straight path of the journey flow. When multiple modules in a straight path require overlapping domain elements, the platform groups their data requirements into a single interaction group, so end users provide each piece of information once. If your journey contains evaluation nodes that branch the flow, then the platform creates separate interaction groups for each branch.

​

Interaction Group panel

The Interaction Group panel is a visual tool in the Journey Designer that allows you to review and customise the screens the platform has generated for your hosted journey. You can use it to review navigation flow, view content and layout, preview the end-user experience, and move or adjust fields between pages.

​

Session lifecycle

Each end user verification session in a hosted journey follows a defined lifecycle:

1. Starting a session: Your backend server calls the Start API to initiate a journey instance. The platform returns a secure, short-lived URL.
2. Connecting the device: When the end user opens the URL, the platform establishes a device connection and issues a device token.
3. Completing interactions: The end user progresses through the hosted pages, providing information on each screen.
4. Processing and results: The platform submits data to processing modules. You receive results through callbacks or by querying the journey state.

For a detailed guide on hosted journeys, see Hosted journeys overview.