V1 to v2 migration guide

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

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.

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`	POST	Get the current interaction, its pages, cards, and outstanding domain elements
`/journey/interaction/submit`	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

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.

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:

Call POST /journey/task/list to get pending tasks.
Call POST /journey/task/schema to get the required fields for each task.
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:

Call POST /journey/interaction/fetch to get the current interaction, its domain element requirements, and which elements are still outstanding.
Submit domain elements to POST /journey/interaction/submit with the interactionId and a participants array specifying which domain elements you are submitting.
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

{
  "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

{
  "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.

Execution flow comparison

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

V1 execution flow

How v1 execution worked:

STEPS

Authenticate           → POST /as/token.oauth2
Start journey          → POST /journey/start
Retrieve tasks         → POST /journey/task/list
Retrieve task schema   → POST /journey/task/schema
Submit task data       → POST /journey/task/update
Fetch journey state    → POST /journey/state/fetch

V2 execution flow

How v2 execution works:

STEPS

Authenticate           → POST /as/token.oauth2
Start journey          → POST /journey/start
Fetch interaction      → POST /journey/interaction/fetch
Submit domain elements → POST /journey/interaction/submit
Repeat steps 3–4 until the journey completes
Fetch journey state    → POST /journey/state/fetch

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.

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:

cURL

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:

cURL

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

{
  "status": 404,
  "message": "Not Found Error, validate resource Id",
  "error": "not-found-error"
}

V2 error format

How v2 errors are returned:

JSON

{
  "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.

Migration checklist

Use this checklist to track your migration progress:

Update base URL

Change your API base URL from /captain/api/ to /v2/captain/. Update all regional endpoint references in your configuration.

Verify authentication

No changes are required. Continue using POST /as/token.oauth2 with your existing credentials to obtain access tokens.

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

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.

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.

Adopt the new state response format

Update your response parsing to use the context.process.steps[] array instead of data.process.flow.${variantId}.

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.

Test in your staging environment

Validate your updated integration against the v2 API in a non-production environment before going live.

Next steps

Follow the API-first integration guide for step-by-step instructions on integrating with the v2 API.
Follow the Hosted journey integration guide if you are using hosted journeys.
Review the API reference for full endpoint details.
See the User data input schema for the data model reference.
See the Response advice schema for understanding journey results.
See Error handling for error codes and troubleshooting.
Contact support if you need help with your migration.

Introduction

Migration

Journey execution

Interaction journey execution

What changed in v2

Base URL changes

Authentication changes

API endpoint changes

Journey endpoints

Interaction endpoints (replace task endpoints)

Deprecated v1 task endpoints

From tasks to interactions

How tasks worked in v1

How interactions work in v2

Key differences

Journey state response changes

V1 response structure

V2 response structure

Execution flow comparison

V1 execution flow

V2 execution flow

Data submission changes

V1: Submit task data

V2: Submit domain elements

Error handling changes

V1 error format

V2 error format

HTTP status codes

Migration checklist

Next steps

Introduction

Migration

Journey execution

Interaction journey execution

Documentation Index

​What changed in v2

​Base URL changes

​Authentication changes

​API endpoint changes

​Journey endpoints

​Interaction endpoints (replace task endpoints)

​Deprecated v1 task endpoints

​From tasks to interactions

​How tasks worked in v1

​How interactions work in v2

​Key differences

​Journey state response changes

​V1 response structure

​V2 response structure

​Execution flow comparison

​V1 execution flow

​V2 execution flow

​Data submission changes

​V1: Submit task data

​V2: Submit domain elements

​Error handling changes

​V1 error format

​V2 error format

​HTTP status codes

​Migration checklist

​Next steps

What changed in v2

Base URL changes

Authentication changes

API endpoint changes

Journey endpoints

Interaction endpoints (replace task endpoints)

Deprecated v1 task endpoints

From tasks to interactions

How tasks worked in v1

How interactions work in v2

Key differences

Journey state response changes

V1 response structure

V2 response structure

Execution flow comparison

V1 execution flow

V2 execution flow

Data submission changes

V1: Submit task data

V2: Submit domain elements

Error handling changes

V1 error format

V2 error format

HTTP status codes

Migration checklist

Next steps