Skip to main content

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.

Once you have a customer access token, you can start a journey instance. This creates a new execution of the published journey and returns an instanceId that you use in subsequent API calls.
Use the Start journey (/journey/start) endpoint to start a customer verification journey. You must include a valid access token in your request.

​
Before you start a journey

Before sending the request, make sure you have:
  • Published API journey: A published API journey in preview or production environment. You need the journey’s resource ID and version to start a journey instance.
  • Access token: obtained in Step 1: Authenticate for API authentication.
  • Journey Resource ID: Specific journey Resource ID. Click Dashboard in the GBG GO platform to find the Resource ID for your published journey.
  • Journey version: Specific journey version number. Click Dashboard in the GBG GO platform to find the version number for your published journey.

​
Choose how to start the journey

There are two execution modes:
ModeDescription
Partial prefill modeYou supply domain elements you already have upfront in the context.subject object when starting the journey. The remaining domain elements are collected from the end user through interactions.
Non-prefill modeYou start the journey with an empty subject object. All required data is collected from the end user through interactions.
Use partial prefill mode when you already have some verified user data. Use non-prefill mode if the end user will provide all their data during the journey.

​
Start a journey (non-prefill mode)

If you are not including any user data, send an empty subject object along with the delivery configuration:
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": "97c8b0c5272ba450c48899cc78f6e3f3ba89b5d131c42f7ea972588bd8213b3e@y5z6bj7o",
    "context": {
      "config": { "delivery": "api" },
      "subject": {}
    }
  }'

​
What happens

  • A journey instance is created.
  • The response includes an instanceId that you use in all subsequent steps.
  • All required domain elements must be collected from the end user through interactions.

​
Start a journey (partial prefill mode)

If you already have customer data that you don’t want to ask the end user for again, you can supply it upfront when starting the journey. To do this, remove those domain elements from the Interaction Group panel in the journey builder. This moves the domain elements to the start interaction, which means they can be supplied through partial prefill in the context.subject object when you start the journey. For example, if your journey collects the customer’s full name and date of birth, and you already have it, remove FullName and DateOfBirth from the interaction group.
Remove domain elements from the interaction group
It then moves to the start interaction.
Domain elements moved to the start interaction
To see the start interaction in the journey builder, click the Start of journey node in the Journey builder. This shows the domain elements that can be prefilled when starting the journey. In this example, FullName and DateOfBirth can be prefilled. You can include it in the context.subject object instead. For example:
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": "97c8b0c5272ba450c48899cc78f6e3f3ba89b5d131c42f7ea972588bd8213b3e@y5z6bj7o",
    "context": {
      "config": { "delivery": "api" },
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01"
        }
      }
    }
  }'
The data must follow the domain element schema paths. Depending on the data you are passing, your request looks something like this:
The structure of the context.subject object must follow the domain element schema paths configured for your journey. Always check the schema before sending data. Providing data in the wrong structure results in validation errors or incomplete journeys. To check the required fields and structure for your journey, navigate to Dashboard in the GBG GO platform, click the Actions list for your journey, and click View schema. This shows the expected data structure for the subject object.

​
What happens

  • A journey instance is created with the prefilled data applied.
  • Domain elements that match the prefilled data may already be satisfied, reducing the number of interactions.
  • Any remaining required domain elements are collected from the end user through interactions.

​
Request body fields

FieldRequiredDescription
resourceIdYesThe unique identifier for the published journey, in the format {hash}@{version}.
context.config.deliveryYesThe delivery mode. Set to "api".
context.subjectYesAn empty object {} for non-prefill mode, or structured identity data for partial prefill mode.

​
Successful response

If your request is successful, the API returns a 201 Created response:
JSON
{
  "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
  "status": "started",
  "message": "Journey Pq_hhIX6-sHUy9FLSDzPLu started successfully"
}

​
Response fields

FieldDescription
instanceIdUnique identifier for this journey instance. Use this in all subsequent calls.
statusIndicates the result of the start request.
messageHuman-readable confirmation message.
Save the instanceId, you need it for every subsequent API call in this journey.
Replace @latest with your specific journey version for production integrations. For example: "resourceId": "97c8b0c5272ba450c48899cc78f6e3f3ba89b5d131c42f7ea972588bd8213b3e@y5z6bj7o".Using @latest can introduce a small delay in processing.

​
What happens after starting a journey

Once a journey is successfully started:
  • The platform begins orchestrating verification modules in the background. No work completes synchronously within the start call itself.
  • If prefilled data was used, some domain elements may already be satisfied when you fetch the first interaction.

​
Best practices

  • Always confirm that the journey has been published before attempting to start it.
  • Use the exact resourceId for your target environment. Resource IDs differ between staging and production.
  • For partial prefill mode, always retrieve and validate against the schema before sending data. Incorrect data structures result in validation errors.

​
FAQ

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.
The config object is included inside context when you start a journey. It controls how the journey is delivered to the end user.The primary value you can set is delivery, which determines the delivery mode:
  • page: Use this for GBG hosted journeys (low-code). When delivery is set to "page", the start response includes an instanceUrl, which is a GBG-hosted page URL that you redirect the end user to. The platform handles the entire user interface.
  • api: Use this for API-first integration. When delivery is set to "api", the start response does not include an instanceUrl. You are responsible for building the user interface and collecting data from the end user.
Example with hosted delivery:
JSON
{
  "resourceId": "your-resource-id@latest",
  "context": {
    "config": {
      "delivery": "page"
    },
    "subject": {}
  }
}
Example for API-first integration:
JSON
{
  "resourceId": "your-resource-id@latest",
  "context": {
    "config": {
      "delivery": "api"
    },
    "subject": {}
  }
}
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
{
  "resourceId": "your-resource-id@latest",
  "context": {
    "config": {
      "delivery": "api"
    },
    "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.

​
Next step

Go to Step 3: Fetch the interaction to retrieve the current interaction.