Step 2: Start a journey

Start a customer verification journey using the GBG GO API to create a trackable journey instance with assigned tasks.

Once you’ve authenticated and obtained an access token, the next step is to start a customer journey.

Starting a journey creates a journey instance that can be tracked, assigned tasks, and progressed using additional API calls.

Use the Start journey (/journey/start) endpoint to start a customer verification journey. Also, you must include a valid access token in your request to start a journey.

Prerequisites

• A published journey – A business user must create and publish the journey in the GBG GO platform.
• Journey resource ID – A unique identifier for the journey. You can use a specific version, for example, @2z5wz848, or the latest version, @latest.
• Access token – Obtained from the Authenticate step.

Choose how to start the journey

There are two execution modes:

Mode	Description
Prefill mode	You send customer data upfront in the request. The system might auto-complete matching tasks. By default, prefill mode operates synchronously, which means the /journey/start response returns only after processing is complete for all modules. You can also start a prefill journey in asynchronous mode, which means that the /journey/start call initiates the journey and return the instance ID and the processing happens asynchronously. Async prevents timeout issues with long-running processes.
Non-prefill mode	You start the journey without user data. Required details must be submitted via tasks later.

Use prefill mode when you already have verified user data. Use non-prefill mode if the customer will provide their data during the journey.

In synchronous prefill execution, If module processing fails to complete, a 5xx error is returned.

Start a journey (non-prefill mode)

If you’re not including any user data, then send a request in the following format to the Start journey (/journey/start) endpoint:

cURL

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/captain/api/journey/start \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "resourceId": "your-journey-resourceID@latest",
    "context": {
      "subject": {
        "documents": [],
        "biometrics": []
      }
    }
  }'

Replace @latest with your specific journey version. For example: "resourceId": "8c24f3a5b76d09e182c397fd45c91ae3f8b530d7a19e64c2bd93f5a76c48e09f@3x5wz848".

Note that using @latest can have a small delay in processing.

What happens

• A journey instance is created.
• The response includes an instanceId which you’ll use in later steps.
• All required tasks will need to be completed manually.

Start a journey (prefill mode)

If you already have user data, then include it in the context object by sending a request to the same Start journey (/journey/start) endpoint. To know what and how to pass the user data, check the User data schema reference. Depending on the user data you’re passing, your request looks something like this:

cURL

curl --request POST \
  --url https://eu.platform.go.gbgplc.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": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01",
          "emails": [
            {
              "type": "work",
              "email": "[e-mail]"
            }
          ]
        },
        "documents": [],
        "biometrics": []
      }
    }
  }'

The structure of the context object depends on the schema configured in the GBG GO platform. Always check the schema before sending data.

Start a journey (async: prefill mode)

To start a journey in asynchronous mode, include "async": true in the config object within your request context, as shown below:

cURL

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/captain/api/journey/start \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "resourceId": "your-journey-resourceID@latest",
    "context": {
     "config": { "async": true},
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01",
          "emails": [
            {
              "type": "work",
              "email": "[e-mail]"
            }
          ]
        },
        "documents": [],
        "biometrics": []
      }
    }
  }'

Get the schema

The schema defines the required fields, formats, and structure for customer data. Refer to User data schema for an explanation of the schema for passing customer data.

To retrieve the schema for your journey:

1. Log in to the GBG GO platform.
2. Go to the Journey Dashboard.
3. Locate your journey.
4. Click Schema.

Providing data in the wrong structure will result in validation errors or incomplete journeys.

What happens after starting a journey

Once a journey is successfully started:

• You’ll receive an instanceId.
• You can now fetch assigned tasks, retrieve schemas, and submit task data.
• If prefilled data was used, then some tasks may already be completed.

Next step

Go to Retrieve tasks to get the list of tasks assigned to the journey.