> ## 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.
# Step 2: Start a journey
> Create a new interaction journey instance using the v2 API.
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)`](/docs/go-v2/api-reference/endpoint/start-journey) 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](/docs/go-v2/developer-integration/execute-customer-journeys/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 interactions. |
| **Non-prefill mode** | You 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:
```bash cURL theme={null}
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](/docs/go-v2/low-code-builder/interactions/explore-interactions) 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 theme={null}
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
| 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 `"api"`. |
| `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 JSON theme={null}
{
"instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
"status": "started",
"message": "Journey Pq_hhIX6-sHUy9FLSDzPLu started successfully"
}
```
### Response fields
| Field | Description |
| ------------ | ------------------------------------------------------------------------------ |
| `instanceId` | Unique identifier for this journey instance. Use this in all subsequent calls. |
| `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.
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 JSON theme={null}
{
"resourceId": "your-resource-id@latest",
"context": {
"config": {
"delivery": "page"
},
"subject": {}
}
}
```
Example for API-first integration:
```json JSON theme={null}
{
"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 JSON theme={null}
{
"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](/docs/go-v2/developer-integration/execute-customer-journeys/retrieve-tasks-step) to retrieve the current interaction.