> ## 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.

# V1 to v2 migration guide

> Migrate your integration from the GBG GO v1 API to v2.

This guide helps you migrate your existing GBG GO v1 API integration to v2. It covers what changed, how to update your API calls, and a step-by-step checklist to complete the migration.

## What changed in v2

V2 introduces several improvements to how you integrate with GBG GO:

| Area                | V1                                                        | V2                                                                       |
| ------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Base URL**        | `https://{region}.platform.go.gbgplc.com/captain/api/`    | `https://{region}.platform.go.gbgplc.com/v2/captain/`                    |
| **Data collection** | Task-based: retrieve tasks, get schemas, submit task data | Interaction-based: fetch the current interaction, submit domain elements |
| **Authentication**  | Single bearer token for all operations                    | Same bearer token model with `POST /as/token.oauth2`                     |
| **Journey start**   | Returns results synchronously                             | Returns immediately with an `instanceId`; poll for results               |
| **Journey results** | Results nested under `data.process.flow.${variantId}`     | Structured `context.process.steps[]` array                               |
| **Error format**    | `{ status, message, error }`                              | Structured `errors[]` array with `code`, `name`, `problem`, and `action` |

## Base URL changes

Update your API base URL from `/captain/api/` to `/v2/captain/`:

| Version | Base URL                                               |
| ------- | ------------------------------------------------------ |
| V1      | `https://{region}.platform.go.gbgplc.com/captain/api/` |
| V2      | `https://{region}.platform.go.gbgplc.com/v2/captain/`  |

Regional endpoints remain the same:

| Region | V2 base URL                                     |
| ------ | ----------------------------------------------- |
| EU     | `https://eu.platform.go.gbgplc.com/v2/captain/` |
| US     | `https://us.platform.go.gbgplc.com/v2/captain/` |
| AU     | `https://au.platform.go.gbgplc.com/v2/captain/` |

The authentication endpoint is unchanged:

```bash BASH theme={null}
https://api.auth.gbgplc.com/as/token.oauth2
```

## Authentication changes

The authentication method remains the same between v1 and v2. You continue to obtain a bearer token using `POST /as/token.oauth2` with your client credentials.

| Detail          | V1                                        | V2                                                    |
| --------------- | ----------------------------------------- | ----------------------------------------------------- |
| **Endpoint**    | `POST /as/token.oauth2`                   | `POST /as/token.oauth2` (unchanged)                   |
| **Grant type**  | `password`                                | `password` (unchanged)                                |
| **Token usage** | Include in `Authorization: Bearer` header | Include in `Authorization: Bearer` header (unchanged) |

No changes are required to your authentication logic. Continue using the same credentials and token flow you already have in place. For reference, see the [Authentication guide](/docs/go-v2/developer-integration/execute-customer-journeys/authenticate).

## API endpoint changes

Here’s a summary of the key API endpoint changes you need to make in your integration:

### Journey endpoints

These endpoints are available in both v1 and v2:

| Endpoint               | Method | Change from v1                                                                           |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------- |
| `/journey/start`       | POST   | Returns `201` with `instanceId` immediately (async). V1 returned results synchronously.  |
| `/journey/state/fetch` | POST   | Response now uses `context.process.steps[]` instead of `data.process.flow.${variantId}`. |

### Interaction endpoints (replace task endpoints)

These endpoints replace the v1 task-based endpoints:

| V2 endpoint                                                                            | Method | Description                                                                    |
| -------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------ |
| [`/journey/interaction/fetch`](/docs/go-v2/api-reference/endpoint/fetch-interaction)   | POST   | Get the current interaction, its pages, cards, and outstanding domain elements |
| [`/journey/interaction/submit`](/docs/go-v2/api-reference/endpoint/submit-interaction) | POST   | Submit domain elements for the current interaction                             |

### Deprecated v1 task endpoints

The following v1 task-based endpoints are deprecated in v2:

| Deprecated endpoint              | V2 replacement                       | Notes                                                      |
| -------------------------------- | ------------------------------------ | ---------------------------------------------------------- |
| `POST /journey/task/list`        | `POST /journey/interaction/fetch`    | Returns the current interaction instead of a list of tasks |
| `POST /journey/task/update`      | `POST /journey/interaction/submit`   | Submits domain elements instead of task data               |
| `POST /journey/task/schema`      | Part of `/journey/interaction/fetch` | Schema information is included in the interaction response |
| `POST /journey/task/list/schema` | Part of `/journey/interaction/fetch` | Schema information is included in the interaction response |

<Warning>
  These task-based endpoints are deprecated and will be removed when v1 is decommissioned. Update your integration to use the v2 interaction endpoints before migration.
</Warning>

## From tasks to interactions

The most significant change in v2 is the move from tasks to interactions.

### How tasks worked in v1

In v1, you retrieved a list of tasks, fetched the schema for each task, and submitted data against a specific `taskId`:

1. Call `POST /journey/task/list` to get pending tasks.
2. Call `POST /journey/task/schema` to get the required fields for each task.
3. Submit data to `POST /journey/task/update` with the `taskId` and `"intent": "Complete"`.

### How interactions work in v2

In v2, you work with one interaction at a time. Each interaction declares which domain elements it needs to collect, for example, `FullName`, `DateOfBirth`, `CurrentAddress` and includes its layout structure (pages and cards) directly in the response:

1. Call `POST /journey/interaction/fetch` to get the current interaction, its domain element requirements, and which elements are still outstanding.
2. Submit domain elements to `POST /journey/interaction/submit` with the `interactionId` and a `participants` array specifying which domain elements you are submitting.
3. The journey automatically advances to the next interaction when all required domain elements are submitted.

### Key differences

| Aspect           | V1 (tasks)                                           | V2 (interactions)                                                                                       |
| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Active items** | Multiple tasks could be pending                      | One interaction is active at a time                                                                     |
| **Schema**       | Separate `POST /journey/task/schema` call            | Included in the `/journey/interaction/fetch` response (`collects[]`, `outstanding[]`, pages, and cards) |
| **Advancement**  | Explicit task completion with `"intent": "Complete"` | Automatic when all required domain elements are submitted                                               |
| **Identifier**   | `taskId`                                             | `interactionId`                                                                                         |
| **Auth token**   | Bearer token                                         | Bearer token                                                                                            |

## Journey state response changes

The structure of the journey state response has changed significantly.

### V1 response structure

Sample v1 response:

```json JSON theme={null}
{
  "status": "Completed",
  "instanceId": "abc123",
  "metaData": {
    "createdTime": "2024-02-15T22:16:33.213Z",
    "completedTime": "2024-02-15T22:17:45.123Z"
  },
  "data": {
    "process": {
      "flow": {
        "variant-id-1": {
          "result": { ... },
          "subject": { ... }
        }
      }
    }
  }
}
```

### V2 response structure

Sample v2 response:

```json JSON theme={null}
{
  "instanceId": "P7U7Licy40cLZiENe8MrsL",
  "status": "Completed",
  "context": {
    "process": {
      "journey": {
        "name": "Journey Name",
        "startedAt": "2026-03-16T23:56:04.097Z",
        "id": "journey-id",
        "version": "version-id"
      },
      "instance": {
        "id": "P7U7Licy40cLZiENe8MrsL"
      },
      "steps": [
        {
          "advice": {
            "contains": {
              "nameAddress": 1,
              "nameDob": 1,
              "nameDobAddress": 1,
              "idNameAddress": 1,
              "idNameDob": 1,
              "idNameAddressDob": 1,
              "idName": 1,
              "sources": 1,
              "isUnder18": false,
              "customDecision": null,
              "gbgScore": 400
            }
          },
          "outcome": "Match"
        }
      ]
    },
    "subject": {},
    "result": {
      "status": "pending",
      "advice": {}
    }
  }
}
```

**What to update in your parsing logic:**

* Results are now in `context.process.steps[]` instead of `data.process.flow.${variantId}`.
* Each step includes an `advice` object with match scores and an `outcome` field.
* Journey metadata (name, start time, ID, version) is available under `context.process.journey`.

For the full response schema, see [Response advice schema](/docs/go-v2/api-reference/response-schema).

## Execution flow comparison

Let's compare the execution flow between v1 and v2:

### V1 execution flow

How v1 execution worked:

```json STEPS theme={null}
1. Authenticate           → POST /as/token.oauth2
2. Start journey          → POST /journey/start
3. Retrieve tasks         → POST /journey/task/list
4. Retrieve task schema   → POST /journey/task/schema
5. Submit task data       → POST /journey/task/update
6. Fetch journey state    → POST /journey/state/fetch
```

### V2 execution flow

How v2 execution works:

```json STEPS theme={null}
1. Authenticate           → POST /as/token.oauth2
2. Start journey          → POST /journey/start
3. Fetch interaction      → POST /journey/interaction/fetch
4. Submit domain elements → POST /journey/interaction/submit
5. Repeat steps 3–4 until the journey completes
6. Fetch journey state    → POST /journey/state/fetch
```

<Note>
  Steps 3 and 4 repeat for each interaction in the journey. The journey advances automatically when all required domain elements for the current interaction are submitted.
</Note>

## Data submission changes

The data submission process has changed from submitting task data to submitting domain elements for interactions.

### V1: Submit task data

Sample v1 request to submit task data:

```bash cURL theme={null}
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/captain/api/journey/task/update \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "intent": "Complete",
    "instanceId": "your-instance-id",
    "taskId": "your-task-id",
    "context": {
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01"
        }
      }
    }
  }'
```

### V2: Submit domain elements

Sample v2 request to submit domain elements:

```bash cURL theme={null}
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/interaction/submit \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "your-instance-id",
    "interactionId": "your-interaction-id",
    "participants": [
      { "domainElementId": "FullName" },
      { "domainElementId": "DateOfBirth" }
    ],
    "context": {
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01"
        }
      }
    }
  }'
```

**Key differences:**

* No `intent` field: V2 does not require `"intent": "Complete"`. The journey advances automatically when all required domain elements are submitted.
* `interactionId` replaces `taskId`: Use the interaction identifier from the `/journey/interaction/fetch` response.
* `participants` array: V2 requires a `participants` array that lists which domain elements you are submitting.
* Base URL change: Note the updated base URL (`/v2/captain/` instead of `/captain/api/`).

## Error handling changes

V2 uses a standardised error response format across all endpoints.

### V1 error format

How v1 errors were returned:

```json JSON theme={null}
{
  "status": 404,
  "message": "Not Found Error, validate resource Id",
  "error": "not-found-error"
}
```

### V2 error format

How v2 errors are returned:

```json JSON theme={null}
{
  "errors": [
    {
      "code": "4002",
      "name": "MISSING_FIELD",
      "location": "Body",
      "problem": "Either resourceId or deliveryId is required",
      "action": "Please provide resourceId (e.g., 'my-delivery@latest') or deliveryId"
    }
  ]
}
```

V2 error responses include a structured `errors[]` array. Each error contains:

| Field      | Description                                                               |
| ---------- | ------------------------------------------------------------------------- |
| `code`     | Numeric error code (as a string)                                          |
| `name`     | Machine-readable error identifier (for example, `MISSING_FIELD`)          |
| `location` | Where the error originated: `Body`, `Authorization`, `Path`, or `Service` |
| `problem`  | Human-readable description of what went wrong                             |
| `action`   | Suggested resolution                                                      |

All responses include an `X-Request-ID` header that you can provide to GBG support for troubleshooting.

### HTTP status codes

| HTTP status | Meaning               | Action                                                  |
| ----------- | --------------------- | ------------------------------------------------------- |
| 200         | OK                    | Request successful.                                     |
| 201         | Created               | New resource created successfully.                      |
| 400         | Bad request           | Fix request data. Do not retry.                         |
| 401         | Unauthorized          | Refresh your token. Do not retry with the same token.   |
| 403         | Forbidden             | Check your account permissions. Do not retry.           |
| 404         | Not found             | Verify the URL and resource ID.                         |
| 405         | Method not allowed    | Confirm the correct HTTP method for the endpoint.       |
| 409         | Conflict              | The domain element was already submitted. Do not retry. |
| 500         | Internal server error | Retry with exponential backoff.                         |
| 503         | Service unavailable   | Retry after a short delay.                              |

For more details, see [Error handling](/docs/go-v2/developer-integration/error-handling).

## Migration checklist

Use this checklist to track your migration progress:

<Steps>
  <Step title="Update base URL">
    Change your API base URL from `/captain/api/` to `/v2/captain/`. Update all regional endpoint references in your configuration.
  </Step>

  <Step title="Verify authentication">
    No changes are required. Continue using `POST /as/token.oauth2` with your existing credentials to obtain access tokens.
  </Step>

  <Step title="Replace task endpoints with interaction endpoints">
    Replace your task-based API calls with the v2 interaction equivalents:

    * `POST /journey/task/list` → `POST /journey/interaction/fetch`
    * `POST /journey/task/update` → `POST /journey/interaction/submit`
    * `POST /journey/task/schema` → included in the `/journey/interaction/fetch` response
  </Step>

  <Step title="Update data submission logic">
    Remove the `"intent": "Complete"` field from submit requests. Replace `taskId` with `interactionId`. Add the `participants` array to specify which domain elements you are submitting.
  </Step>

  <Step title="Handle async journey start">
    Update your `/journey/start` integration to handle the `201` response with `instanceId`. Use `POST /journey/state/fetch` to poll for journey completion.
  </Step>

  <Step title="Adopt the new state response format">
    Update your response parsing to use the `context.process.steps[]` array instead of `data.process.flow.${variantId}`.
  </Step>

  <Step title="Update error handling">
    Update your error parsing to handle the new `errors[]` array format with `code`, `name`, `problem`, `action`, and `location` fields. Handle the HTTP 409 status for duplicate domain element submissions. Use the `X-Request-ID` header when contacting GBG support.
  </Step>

  <Step title="Test in your staging environment">
    Validate your updated integration against the v2 API in a non-production environment before going live.
  </Step>
</Steps>

## Next steps

* Follow the [API-first integration guide](/docs/go-v2/developer-integration/overview) for step-by-step instructions on integrating with the v2 API.
* Follow the [Hosted journey integration guide](/docs/go-v2/low-code-builder/execution-guides/overview) if you are using hosted journeys.
* Review the [API reference](/docs/go-v2/api-reference/overview) for full endpoint details.
* See the [User data input schema](/docs/go-v2/api-reference/schema) for the data model reference.
* See the [Response advice schema](/docs/go-v2/api-reference/response-schema) for understanding journey results.
* See [Error handling](/docs/go-v2/developer-integration/error-handling) for error codes and troubleshooting.
* [Contact support](https://www.gbg.com/en/contact/customer-support/) if you need help with your migration.