Step 2: Start a journey

Create a new interaction journey instance using the v2 API.

Once you have an 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 all subsequent API calls.

Before you start a journey

Before sending the request, make sure you have:

• Published hosted journey: A published hosted 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:

Mode	Description
Partial prefill mode	You 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 the hosted journey page.
Non-prefill mode	You start the journey with an empty subject object. All required data is collected from the end user through the hosted journey page.

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 hosted 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:

BASH

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": "page" },
      "subject": {}
    }
  }'

What happens

• A journey instance is created.
• The response includes an instanceId and instanceUrl that you use in subsequent steps.
• All required domain elements are collected from the end user through the hosted journey page.

Start a journey (partial prefill mode)

If you already have customer data that you don’t want to ask the end user for again through the hosted journey, 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.

It then moves 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:

BASH

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": "page" },
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01"
        }
      }
    }
  }'

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, so the end user won’t be asked for them again on the hosted journey page.
• Any remaining required domain elements are collected from the end user through the hosted journey page.

Request body fields

Field	Required	Description
resourceId	Yes	The unique identifier for the published journey, in the format {hash}@{version}.
context.config.delivery	Yes	The delivery mode. Set to "page" for hosted journeys.
context.subject	Yes	An 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": "P7U7Licy40cLZiENe8MrsL",
  "instanceUrl": "/journey/P7U7Licy40cLZiENe8MrsL",
  "status": "started",
  "message": "Journey P7U7Licy40cLZiENe8MrsL started successfully"
}

Response fields

Field	Description
instanceId	Unique identifier for this journey instance. Use this in all subsequent calls.
instanceUrl	The URL path for the hosted journey page.
status	Indicates the result of the start request.
message	Human-readable confirmation message.

Save the instanceId, you need it for every subsequent API call in this journey.

Hosted journey sessions are single-use and cannot be resumed. If the end user closes or leaves the hosted journey page, the session cannot be continued. The session URL is also valid for a limited time. If the session expires or is abandoned, then start a new journey instance to generate a fresh URL.

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.