The GBG GO API allows you to trigger customer journeys programmatically, track their progress, and submit customer data as needed.

If you’re building an integration with the GBG GO API, then you’ll need to make a series of API calls to execute a journey successfully. Each step involves retrieving the required information, handling customer input, and progressing the journey toward completion.

This guide walks you through the process step by step. You’ll find explanations, best practices, and request examples to help you integrate the GBG GO API into your system.

​

Before you begin

Before you start integrating with the GBG GO API, make sure you have everything in place:

• A published customer journey: A business user must first design and publish the customer journey in the GBG GO platform. If you’re unsure about this step, then check with your team to confirm that the journey is ready to use.
• API access and credentials: To interact with the API, you’ll need an API Client ID, Client Secret, Username, and Password. You can get these from your account manager. For more information, see the Authentication guide for details.
• An understanding of the verification process: Your customer journey might involve tasks such as document collection, identity verification, and biometric checks. Ensure that you know which steps are required in your specific use case.

​

Step-by-step customer journey execution

To execute a complete customer journey, you must complete the following steps in order. They are explained fully in the steps below.

1. Authenticate: Obtain an access token to authorize API requests. Without authentication, your requests will be rejected. 🔗 Go to Authentication guide
2. Start a journey: Trigger a new customer journey using a journey ID (known as resource ID). This creates a journey instance, which you’ll track. 🔗 Go to Start journey guide
3. Retrieve tasks: Fetch the list of assigned tasks for the customer. Tasks define the required actions (e.g., document upload, verification). 🔗 Go to Retrieve tasks guide
4. Manage schemas: Retrieve task schemas to understand the required data structure before submitting information. 🔗 Go to Manage schemas guide
5. Submit task data: Send customer input (e.g., document uploads, identity verification) to complete tasks in the journey. 🔗 Go to Submit data guide
6. Fetch journey state: Track the current status of the journey (In Progress, Completed) and retrieve timestamps. 🔗 Go to Fetch state guide

​

Step 1: Authenticate

Before you can interact with the GBG GO API, you need to authenticate. This means obtaining an access token, which acts as a temporary credential to authorize API calls. Without this token, all requests will be rejected.

Your access token is required in every request, so let’s go through how to get one.

​

Get your API credentials

Before you can request an access token, you’ll need your API credentials. These credentials verify your organization and allow you to authenticate with the API.

You can get your API credentials from your account manager. These include:

• Client ID: A unique identifier assigned to your organization. This links API requests to your account.
• Client secret: A confidential key that validates your access. Never expose this in frontend applications.
• Username: The API username associated with your account.
• Password: A temporary password that must be reset before authentication.

​

Send the authentication request

Now that you have your credentials, the next step is to exchange them for an access token. This token grants temporary access and must be included in all API requests.

To get an access token, send a POST request to the Generate access token endpoint (/as/token.oauth2). The request must include:

• Client ID and client secret: These verify your organization’s access.
• Username and password: These authenticate your user account.
• Grant type: Always set to "password", as the API uses the OAuth 2.0 password grant type.

Your request will look like this:

curl --request POST \
     --url https://gbggo4-demo-eu.nonprod.fabric.gbgplatforms.com/captain/api/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'

If authentication is successful, then the API returns an access token:

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

​

Step 2: Start a journey

Now that you have an access token, you’re ready to start a customer journey.

Before you can start a journey using the API, a business user must first design and publish the journey in the GBG GO platform. Once a journey is published, you can trigger it via the API, creating a journey instance. This instance allows you to track progress, retrieve tasks, and submit required information.

​

Choose how to start a journey

When starting a journey, you can decide whether to provide customer data upfront or let the user complete it during the journey. The method you choose affects how tasks are processed:

• Prefill mode: You provide customer details in the request, allowing the system to auto-complete any tasks that match the provided data.
• Non-prefill mode: The journey starts without any initial customer data. The customer must manually complete required tasks before progressing.

​

Prefill vs. non-prefill execution modes

When starting a journey using the GBG GO API, there are two execution modes:

• Prefill mode: You provide the full context object (user data) upfront in the request. The system evaluates the provided data and may auto-complete certain tasks, reducing manual input.
• Non-prefill mode: No user data is sent in the initial request. Instead, the journey starts with an empty context object, and you must follow a step-by-step process:
  1. Retrieve assigned tasks.
  2. Fetch task schemas to understand required inputs.
  3. Submit task data to progress the journey.

​

What happens when incorrect data is provided in prefill mode?

If the context object in Prefill mode contains incorrect or incomplete data, the system does not reject the request outright. Instead:

• Valid fields are retained: The system accepts correctly formatted fields and pre-fills them in the journey.
• Missing or invalid fields create pending tasks: Any required fields that are missing or incorrect trigger additional tasks that must be completed manually before the journey can progress.

​

When to use each mode

​

Retrieve the schema for prefill mode

If you are using Prefill mode, you must retrieve the schema for your journey from the Journey dashboard in the GBG GO platform. The schema defines:

• The required fields and their formats. These fields represent customer identity details, such as firstName, lastNames, dateOfBirth, and currentAddress, which are essential for verification and matching processes.
• The expected data types (e.g., string, array, object). Each field must follow the correct format to ensure the system processes the data correctly. (See user data schema)
• The structure of the context object. This structure determines how customer information is passed in your API request and what details are needed for tasks such as identity verification, document validation, and fraud detection.

​

Where to find the schema

To retrieve the schema:

1. Log in to the GBG GO platform.
2. Navigate to the Journey dashboard.
3. Locate the journey you are integrating with.
4. Click the Schema button to review or download the schema.

​

Example schema breakdown

Below is an example schema retrieved from the Journey dashboard:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "context": {
      "type": "object",
      "properties": {
        "subject": {
          "type": "object",
          "properties": {
            "identity": {
              "type": "object",
              "properties": {
                "firstName": { "type": "string" },
                "lastNames": {
                  "type": "array",
                  "items": { "type": "string" }
                },
                "currentAddress": {
                  "type": "object",
                  "properties": {
                    "locality": { "type": "string" },
                    "postalCode": { "type": "string" },
                    "country": { "type": "string" }
                  },
                  "required": ["locality", "postalCode", "country"]
                }
              },
              "required": ["firstName", "lastNames", "currentAddress"]
            }
          },
          "required": ["identity"]
        }
      },
      "required": ["subject"]
    }
  },
  "required": ["context"]
}

​

How to use this schema

• Follow the required fields: Any field listed under "required" must be included in your request.
• Use the correct data types: If a field is an array, ensure you send it in that format.
• Match the structure: The schema tells you how to organize identity details correctly.

​

Making an API request to start a journey

Now that you understand Prefill and Non-prefill modes, let’s go over how to start a journey.

​

Prerequisites

Before starting a journey, make sure you have:

• A published journey: A business user must configure and activate the journey in the GBG GO platform.
• A journey resource ID: This unique identifier is assigned when the journey is published. Use @latest to always start the most recent version.
• A valid access token: Every API request must be authenticated. If you haven’t done this yet, get an access token first.

​

Start a journey without prefilled data (Non-prefill mode)

If you don’t provide customer data in the request, then the journey starts without a context object. This means that no user data is sent upfront, and all required customer details must be provided later by completing tasks assigned during the journey.

For example, to start a journey without prefilled data, send the following request:

curl --request POST \
  --url https://gbggo4-demo-eu.nonprod.fabric.gbgplatforms.com/captain/api/journey/start \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "resourceId": "your-journey-resourceId@latest"
  }'

​

What you’re passing in the request

• resourceId – This is the unique identifier of the customer journey you want to start. Every journey published in the GBG GO platform has a resource ID, which you can find in the Journey Dashboard. This tells the API which journey to initiate.
• @latest – This specifies that you want to use the most recent version of the journey. Each time a journey is updated and republished, a new version is created.
  • If you always want to use the latest version, append @latest to the resource ID.
  • If you need to use a specific version, replace @latest with the exact version number, which you can retrieve from the Journey Dashboard.

​

Start a journey with prefilled data (Prefill method)

If you already have customer details, then you can include them in the request when starting a journey. This approach, known as Prefill mode, allows you to provide user data upfront, allowing the system to complete certain tasks automatically without requiring manual input.

By using Prefill Mode, you reduce the number of tasks that need to be manually completed later. However, it’s important to provide accurate data formatted correctly according to the journey schema.

​

Sending a request with prefilled data

For example, to start a journey with prefilled data, send the following request.:

curl --request POST \
  --url https://gbggo4-demo-eu.nonprod.fabric.gbgplatforms.com/captain/api/journey/start \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "resourceId": "your-journey-resourceId@latest",
    "context": {
      "subject": {
        "identity": {
          "firstName": "John",
          "lastNames": ["Doe"],
          "dateOfBirth": "1990-01-01",
          "emails": [
            {
              "type": "work",
              "email": "john.doe@example.com"
            }
          ]
        }
      }
    }
  }'

​

Understanding the request parameters

• resourceId – This is the unique identifier for the journey you are starting. It tells the API which predefined customer journey to execute.

  • You can get the resource ID from the Journey dashboard in the GBG GO platform.
  • Using @latest: This makes the request start the most recent version of the journey. If you need to use a specific version, replace @latest with the exact version number found in the dashboard.

• context – This is the main object where user data is passed. It includes:

  • subject – Represents the person going through the journey.
  • identity – Contains identity-related details such as first name, last name, date of birth, and email.

​

What happens after sending the request?

Once the API receives this request, it does the following:

1. Creates a journey instance – The API starts a new instance of the journey based on the provided resourceId.
2. Evaluates the user data – The system checks if the provided user data matches required tasks in the journey.
3. Automatically completes matching tasks – If any provided fields match what’s required in the journey, those tasks may be marked as complete.
4. Returns an instanceId – This unique identifier allows you to track the progress of the journey and interact with it via other API requests.

​

Step 3: Retrieve tasks

Once a journey starts, tasks are dynamically assigned based on the configured workflow. Tasks represent the actions a customer must complete, such as uploading documents or verifying their identity. Retrieving tasks allows you to track what needs to be done next.

Now, you’ll fetch the list of tasks assigned to a journey instance.

​

When should you retrieve tasks?

Fetching tasks helps you determine the next steps in the journey. You’ll need to retrieve tasks in these situations:

• Immediately after starting a journey – A journey begins with a set of tasks. Fetching tasks lets you see what actions are required.
• After submitting prefilled data – If user data details were included when starting a journey, some tasks may already be marked as complete.
• Before submitting task data – Some tasks require structured inputs. Fetching tasks helps confirm what needs to be provided.
• To check for updates – If a customer has already completed certain tasks, retrieving tasks again verifies their current status.
• Before finalizing the journey – Some workflows require all tasks to be completed before the journey can be considered finished.

​

What do you need before retrieving tasks?

Before making the request, ensure you have:

• A journey instance ID – This is assigned when a journey starts. If you don’t have one, follow the steps in Start a journey.
• An access token – Every API request must be authenticated. If you haven’t done this yet, see Authenticate to get your access token.

​

Retrieve tasks

Send a request to the Retrieve tasks endpoint(/journey/task/list) to get a list of assigned tasks.

Your request will look like this:

curl --request POST \
  --url https://gbggo4-demo-eu.nonprod.fabric.gbgplatforms.com/captain/api/journey/task/list \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "your-instance-id"
  }'

This request fetches all tasks assigned to the journey. The API will return a response containing details about each task. See the API reference for the full response structure.

​

What happens after retrieving tasks?

Once you have the list of tasks, your next steps depend on the response:

• If tasks require customer input, retrieve the task schema to check the required fields. Go to Manage schemas.
• If some tasks are already completed, display only the remaining tasks to the customer.
• If no tasks are returned, check the journey state to determine whether the process is complete.
• Once the customer provides the required information, submit the task data to progress the journey. See Submit data.

Now that you’ve retrieved the list of tasks, the next step is to understand how to handle structured task data. Next, you’ll learn how to manage task schemas so you can submit data correctly.

​

Step 4: Manage schemas

Each task in a journey has a schema that defines the required data structure. The schema specifies what information must be provided to complete the task, including input fields, expected data types, and validation rules.

Now, you’ll retrieve the schema for a task so you can submit data correctly.

​

When should you retrieve a task schema?

Fetching a schema helps you understand what data is required before submitting task information. You’ll need to retrieve a schema in these situations:

• Before submitting task data – The schema outlines what fields must be provided and how they should be structured.
• When implementing dynamic forms – If your application generates input fields dynamically, retrieving the schema ensures you display the correct fields.
• To check for conditional fields – Some fields appear only when certain conditions are met. Fetching the schema helps determine what needs to be displayed.

​

What do you need before retrieving a schema?

Before making the request, ensure you have:

• A journey instance ID – This is assigned when a journey starts. If you don’t have one, follow the steps in Start a journey.
• A task ID – Each task within a journey has a unique identifier. If you don’t have one, first retrieve the task list.
• An access token – Every API request must be authenticated. If you haven’t done this yet, see Authenticate.

​

Retrieve a task schema

Now that you have what you need, send a request to the Fetch task schema endpoint(/journey/task/schema) to get the structure of a specific task.

curl --request POST \
  --url https://gbggo4-demo-eu.nonprod.fabric.gbgplatforms.com/captain/api/journey/task/schema \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "taskId": "your-task-id"
  }'

The API returns the schema for the specified task. See the Fetch task schema API reference for the full request and response format.

​

What happens after retrieving the schema?

Once you have the schema, your next steps depend on the response:

• If the schema includes required fields, ensure you collect and structure the data accordingly.
• If some fields are conditional, check which conditions must be met for them to appear.
• If a customer needs to provide input, display the required fields in your UI.
• Once you’ve gathered the necessary data, you’re ready to submit task data to complete the next step in the journey. See Submit data.

Now that you’ve retrieved the task schema, the next step is submitting the required data to complete the task.

​

Step 5: Submit task data

Each task in a journey requires specific data to progress. This could be identity details, uploaded documents, or verification inputs. Submitting task data ensures that the journey continues toward completion.

Now, you’ll send the required information for a task using the API.

​

When should you submit task data?

You’ll need to submit task data in these situations:

• When a task requires user input – Some tasks cannot proceed without customer-provided details, such as a name, address, or document.
• After retrieving the task schema – The schema outlines the required fields and expected data format.
• When updating an incomplete task – If a task was started but not completed, you can update the data and resubmit it.
• Before finalizing the journey – Certain workflows require all tasks to be completed before the journey reaches a final outcome.

​

What do you need before submitting task data?

Before making the request, ensure you have:

• A journey instance ID – This uniquely identifies the journey execution. If you don’t have one, follow the steps in Start a journey.
• A task ID – Each task within a journey has a unique identifier. If you don’t have one, first retrieve the task list.
• The task schema – The schema defines the required fields for completing the task. Retrieve it using Manage schemas.
• An access token – Every API request must be authenticated. If you haven’t done this yet, see Authenticate.

​

Submit task data

Now that you have what you need, send a request to the Submit task data endpoint(/journey/task/update) to update the task with the required information.

curl --request POST \
  --url https://gbggo4-demo-eu.nonprod.fabric.gbgplatforms.com/captain/api/journey/task/update \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "intent": "COMPLETE",
    "instanceId": "your-instance-id",
    "taskId": "your-task-id",
    "data": {
      "fieldKey1": "value1",
      "fieldKey2": "value2"
    }
  }'

This request submits the required data for the task. See the Submit task data API reference for the complete request format and required fields.

​

What happens after submitting task data?

Once the task data is successfully submitted:

• The task is updated in the system and, if all required fields are provided, marked as completed.
• If additional tasks remain, retrieve the task list again to determine the next required steps. See Retrieve tasks.
• If the task submission is incorrect or incomplete, the API will return a validation error. You’ll need to adjust the data and retry the request.
• If all tasks are completed, check the journey state to determine whether the journey has finished. See Fetch state.

Now that you’ve submitted task data, the next step is to track the journey state to determine whether any further actions are needed.

​

Step 6: Fetch journey state

Tracking the journey state allows you to determine its progress and check whether any tasks are still pending or if the journey has been completed. The API provides real-time updates on the journey’s status, helping you decide what actions to take next.

Now, you’ll retrieve the current state of a journey.

​

When should you fetch the journey state?

You’ll need to check the journey state in these situations:

• After starting a journey – Confirm that the journey instance was created successfully.
• Before retrieving or submitting tasks – Ensure there are active tasks that require action.
• To monitor progress – If the journey consists of multiple steps, checking the state helps track what has been completed and what still needs attention.
• To confirm completion – Some workflows require confirmation that a journey is finished before triggering the next step.
• For troubleshooting – If a journey is stuck or encounters an issue, checking the state helps diagnose potential problems.

​

What do you need before fetching the journey state?

Before making the request, ensure you have:

• A journey instance ID – This is assigned when a journey starts. If you don’t have one, follow the steps in Start a journey.
• An access token – Every API request must be authenticated. If you haven’t done this yet, see Authenticate.

​

Retrieve the journey state

Now that you have what you need, send a request to the Fetch journey state endpoint(/journey/state/fetch) to get the current status of a journey.

curl --request POST \
  --url https://gbggo4-demo-eu.nonprod.fabric.gbgplatforms.com/captain/api/journey/state \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "your-instance-id"
  }'

This request returns details about the journey’s status. See the Fetch journey state API reference for the complete request and response format.

​

What happens after retrieving the journey state?

After fetching the journey state, your next steps depend on the response:

• If the journey is still in progress, retrieve the task list to check what actions are required. See Retrieve tasks.
• If tasks require input, retrieve the task schema to ensure data is submitted in the correct format. See Manage schemas.
• If the journey is completed, no further action is needed unless you want to log the outcome or trigger additional processes.
• If an error occurs, check the response details to troubleshoot issues. See Handle errors.