Hosted journeys quickstart

This quickstart walks you through creating a hosted journey in the GBG GO platform and starting it via the API. By the end, you will have a working hosted journey with a URL that end users can access to complete verification.

Interactive demo

Follow this interactive demo to see how quickly you can create and launch a hosted journey using the GBG GO Journey builder.

For the best experience, expand the demo to full screen using the icon in the top-right corner.

Before you begin

Ensure you have the following:

A GBG GO account. If you do not have an account, then contact your GBG account manager.
You have received a welcome email confirming your account creation.
The necessary modules and variants are enabled in your contract.
API credentials (Client ID, Client secret, username, and password) provided by your GBG account manager.
A published journey with the journey resource ID and version number copied from the GBG GO dashboard.

The login credentials for your GBG GO dashboard are different from your API credentials. The API credentials are separately provided by your GBG account manager. These credentials are used for programmatic access to the GBG GO APIs, while the dashboard login is for the web interface.

Step 1: Log in to GBG GO

This section guides you through accessing GBG GO for the first time. If you are an existing customer, then you do not need to go through these steps.

Navigate to the GBG GO sign-in page, and then click Customer Sign In.
Enter your email address, and then click Log In.
Click Forgot your password? GBG GO sends a recovery code to your email.
Enter the recovery code and create your new password.
Click Change password to complete the setup.
Log in with your email and new password.

You are now logged into the GBG GO dashboard and can begin creating hosted journeys.

Step 2: Create a hosted journey

This section walks you through creating a hosted journey.

Click on the Create a new journey list.
Select API + hosted (latest). This opens the Journey builder, allowing you to design Hosted journey workflows.
Click the edit icon on the journey name at the top of the editor.
Enter a meaningful name, for example, “KYC Verification - New Customers.”
Click outside the name field to save it.

Step 3: Add modules

Modules define the verification steps in your journey. Each module performs a specific function, such as document verification, identity checks, or biometric authentication.

Go to Browse and add modules in the left sidebar.
Use the search bar to find a module by name or capability, for example, Age Verification.
Click the module that you want to add.
Click Add to journey to insert it into the flow. To add more modules, click the ”+” icon between existing nodes in the journey flow.
Click a module inside the journey editor.
Click Configure outcomes to define what happens when a user passes or fails the verification step.
Click Close to apply your configuration.

For a hosted journey, the platform analyses the modules you add and automatically generates the appropriate hosted pages to collect the required information from end users.

Step 4: Publish to preview/sandbox environment

Click Publish to Preview in the journey editor. GBG GO displays a confirmation message. Next, click Dashboard to see:

Environment (Preview)
Version number
Resource ID
Last published
Actions list

Your journey is now available for testing in the preview environment. Use the Resource ID and journey version number to start the journey through the API and test the end-user experience.

Step 5: Authenticate and obtain an access token

Your password must be reset from the temporary one before API authentication. Ask your account manager for help with password reset. Make a POST request to obtain your Bearer token:

cURL

curl --request POST \
 --url https://api.auth.gbgplc.com/as/token.oauth2 \
 --header 'accept: application/json' \
 --header 'content-type: application/x-www-form-urlencoded' \
 --data 'client_id=your-client-id&client_secret=your-client-secret&username=your-username&password=your-password&grant_type=password'

You receive an access token that you’ll use for all subsequent API calls, like this:

JSON

{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Store the access_token value securely. Do not share them in emails, chat messages, client-side code or publicly accessible sites.

If you run into a credentials error when making a token cURL request, it’s most likely your credentials aren’t correct. Contact your account manager for the correct or updated credentials.

Step 6: Start Hosted journey using API

Send a POST request to the /journey/start endpoint with the resource ID of the published hosted journey. Include "delivery": "page" in the config object to indicate that this is a hosted journey.

For API Integration journeys, this field is not required as it defaults to API-first delivery. Or you can set the field to “api” to explicitly start an API-first journey.

Sample request:

cURL

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/start \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "resourceId": "your-journey-resource-id@version",
    "context": {
      "config": {
        "delivery": "page"
      },
      "subject": {}
    }
  }'

Sample response:

JSON

{
    "instanceId": "cdr7CqM-kKalNBSmrFvSZV",
    "instanceUrl": "https://gbggo4-demo-eu.nonprod.fabric.gbgplatforms.com/apps/RJemRypK-BUtAb7e",
    "status": "started",
    "message": "Journey cdr7CqM-kKalNBSmrFvSZV started successfully"
}

Response fields:

Field	Type	Description
`instanceId`	string	The unique identifier for this journey instance. Use this to track the journey’s progress.
`instanceUrl`	string	The URL for the hosted pages where end users complete the verification journey.
`status`	string	The initial status of the journey instance. Returns `started` on successful creation.
`message`	string	A human-readable confirmation message.

Step 7: Direct end users to the hosted page

You can use the instanceUrl in one of the following ways:

Redirect: Redirect end users from your application to the URL.
Share: Send the URL directly to end users via email, SMS, or other communication channels.

The hosted pages handle all front-end concerns, including responsive design, document capture, biometric verification, and form validation.

You can copy the instanceUrl and open it in a browser to simulate the end-user experience and test the hosted journey flow.

This is what it looks like when you open the instanceUrl in a browser:

The user completes the verification steps on the hosted pages. The GBG GO platform processes the user’s input based on the modules and logic you configured in the journey builder. Results and outcomes are determined according to the journey’s design. These results are then available in the Investigation portal in the GBG GO dashboard or can be fetched via API.

Step 8: Fetch journey status

After starting a journey, you can poll for its status by sending a request to the /journey/state/fetch endpoint. For hosted journeys, your backend only needs to fetch journey state to detect when the journey completes. The hosted pages handle the interaction loop automatically. Sample request:

BASH

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/state/fetch \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "PiIuACmx8Q8R7qPnAkLAqBAT",
  }'

Sample response:

JSON

{
  "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
  "status": "Completed",
  "context": {
    "subject": {
      "identity": {
        "lastNames": [
          "Doe"
        ],
        "dateOfBirth": "1982-09-27",
        "phones": [
          {
            "type": "mobile",
            "number": ""
          }
        ],
        "currentAddress": {
          "lines": [
            "New Orleans, Louisiana, U.S."
          ],
          "locality": "New Orleans",
          "postalCode": "900010",
          "country": "US"
        },
        "firstName": "John",
        "middleNames": [
          "Michael"
        ]
      }
    },
    "result": {
      "advice": {},
      "status": "complete"
    },
    "process": {
      "instance": {
        "id": "Pq_hhIX6-sHUy9FLSDzPLu",
        "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu"
      },
      "journey": {
        "id": "9dcd95e06495ec32c9ad149283a935548e4a380461b9ee6981af0fef5c70c8c3",
        "version": "5f7yigc4",
        "name": "Age verification",
        "endedAt": "2026-03-16T23:57:38.417Z",
        "durationMilliSec": 94320,
        "terminateInteraction": {
          "grId": "grn:::gbg:design:interaction:end@latest",
          "resource": {
            "id": "end",
            "name": "interactionEnd",
            "version": "latest",
            "type": "interaction",
            "data": {
              "pages": [
                {
                  "id": "pagesForEnd",
                  "cards": [
                    {
                      "id": "AllDoneCard"
                    }
                  ]
                }
              ]
            }
          },
          "collects": [],
          "consumes": []
        },
        "startedAt": "2026-03-16T23:56:04.097Z"
      },
      "steps": [
        {
          "moduleId": "US_AgeVerification_Source1IncludingDOB",
          "result": {
            "note": {
              "expectid_age": {
                "id_number": "6554532688"
              }
            },
            "advice": {
              "address_risk_capabilities": [],
              "dob_risk_capabilities": [],
              "subject_risk_capabilities": [],
              "alert_list_capabilities": [],
              "acceptance_result_capabilities": [],
              "age_result_capabilities": [
                "resultcode.confirm.age"
              ],
              "trust_usa_risk_capabilities": [],
              "trust_usa_result_capabilities": [],
              "ssn_risk_capabilities": [],
              "age_restricted_capabilities": [],
              "name_risk_capabilities": [],
              "match_result_capabilities": []
            },
            "outcome": "Of Age",
            "status": "complete"
          },
          "subject": {
            "identity": {
              "currentAddress": {
                "locality": "New Orleans",
                "postalCode": "900010",
                "country": "US",
                "lines": [
                  "New Orleans, Louisiana, U.S."
                ]
              },
              "firstName": "John",
              "middleNames": [
                "Michael"
              ],
              "lastNames": [
                "Doe"
              ],
              "dateOfBirth": "1982-09-27",
              "phones": [
                {
                  "number": "",
                  "type": "mobile"
                }
              ]
            }
          },
          "process": {
            "instance": {
              "id": "Pq_hhIX6-sHUy9FLSDzPLu",
              "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu"
            },
            "journey": {
              "id": "9dcd95e06495ec32c9ad149283a935548e4a380461b9ee6981af0fef5c70c8c3",
              "version": "5f7yigc4",
              "name": "Age verification",
              "startedAt": "2026-03-16T23:56:04.097Z"
            }
          }
        }
      ]
    }
  }
}

In the response above, John Doe’s age is verified using the Age Verification module. The result is “Of Age,” and the journey is complete. The response also includes the full subject data and module result details. Next, view verification results, data and outcomes in the Investigation portal in the GBG GO dashboard. Based on the status field, take appropriate actions:

Status	Meaning
`InProgress`	The journey is still active. Retrieve remaining tasks.
`Completed`	The journey is done. No further action is needed.
`Failed`	The journey encountered an error. Review previous steps or retry.

Next steps

To learn more about hosted journeys, see Hosted journeys overview.
To explore API capabilities, see the API reference documentation.
To understand the full API integration flow, see API usage guides.
To review customer session results and submitted data, see Investigate overview.

Get Started

Platform

API-first integration

Hosted journey

Digital IDs

Resources

Interactive demo

Before you begin

Step 1: Log in to GBG GO

Step 2: Create a hosted journey

Step 3: Add modules

Step 4: Publish to preview/sandbox environment

Step 5: Authenticate and obtain an access token

Step 6: Start Hosted journey using API

Step 7: Direct end users to the hosted page

Step 8: Fetch journey status

Next steps

Get Started

Platform

API-first integration

Hosted journey

Digital IDs

Resources

Documentation Index

​Interactive demo

​Before you begin

​Step 1: Log in to GBG GO

​Step 2: Create a hosted journey

​Step 3: Add modules

​Step 4: Publish to preview/sandbox environment

​Step 5: Authenticate and obtain an access token

​Step 6: Start Hosted journey using API

​Step 7: Direct end users to the hosted page

​Step 8: Fetch journey status

​Next steps

Interactive demo

Before you begin

Step 1: Log in to GBG GO

Step 2: Create a hosted journey

Step 3: Add modules

Step 4: Publish to preview/sandbox environment

Step 5: Authenticate and obtain an access token

Step 6: Start Hosted journey using API

Step 7: Direct end users to the hosted page

Step 8: Fetch journey status

Next steps