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

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:

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

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

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:

STEPS

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

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:

1. Update base URL

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

2. Verify authentication

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

3. 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
4. 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.

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

6. Adopt the new state response format

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

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

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