V1 to v2 migration guide - GBG Documentation

v2 of GBG GO is only available to a few specific customers in certain regions. Please do not try to migrate without speaking to a representative from GBG. We want to make sure v2 is performing as expected with feature parity of v1 before we invite all customers to migrate.

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`
Execution model	Synchronous or asynchronous, selected with a config option	Asynchronous: the start request returns immediately, then you poll for results
Delivery type	Not part of the start request	Requires `context.config.delivery` in the start request
Journey results	Results nested under `data.process.flow.${variantId}`	`context.process.result` object for the overall outcome, plus a structured `context.process.steps[]` array
Error format	`{ status, message, error }`	Structured `errors[]` array with `code`, `name`, `problem`, and `action`

What stays the same

Your data model and business logic do not change. Only the API integration layer changes. The following are unchanged between v1 and v2:

Prefill data: The context.subject structure with identity fields is the same as v1.
Authentication provider: You continue to use the same bearer tokens from the same provider.
Journey statuses: The InProgress, Completed, and Error statuses are unchanged.
Module execution: The same verification modules run, such as document checks and face matching.
Journey design: You continue to build journeys in the same GBG GO platform.

V1 and v2 journeys are not compatible with each other. You continue to build journeys in the same platform, but you cannot migrate an existing v1 journey to v2. A business user must create new v2 journeys in the GBG GO platform before you migrate.Not all modules and variants are compatible across v1 and v2 either. For example, the v1 variants of the document modules (Document Classification, Document Extraction, and Document Authentication) are not available in v2, which has its own V2 variants of these modules. Check the module pages for the variants available in v2 when you rebuild a journey.

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.

Journey permissions

While your token and credentials do not change, your API client must have the journey permissions assigned before you migrate. These permissions cover starting a journey, reading journey state, and submitting journey data.

If the required permissions are not assigned, then v2 rejects your requests with a 401 or 403 error, even when your token is valid. Work with GBG to confirm your API client has the journey permissions before cutover.

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 could return results synchronously or asynchronously, depending on a config option.
`/journey/state/fetch`	POST	Response now uses `context.process.steps[]` instead of `data.process.flow.${variantId}`.
`/{instanceId}/terminate`	POST	Replaces the v1 `POST /journey/state/delete` for cleanup. The `instanceId` is now part of the path.

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.

Journey start request changes

The journey start request changes in v2: you must specify a delivery type. You still identify the journey with a resourceId, the same as in v1. Before you start a journey, make sure that:

The journey is published: A business user must publish the journey in the GBG GO platform before you can start it, the same as in v1.
The region matches: Send the start request to the base URL for the region where the journey is configured.

Identify the journey with resourceId

V2 identifies the journey with a resourceId in the id@version format, the same as v1, where the version is the published journey version. Use @latest to start the most recent published version.

Specify the delivery type

V2 requires the context.config.delivery field to tell the API how the journey is delivered. The field accepts one of two values:

api: Use this value when you drive the journey through API calls, without a hosted user interface.
page: Use this value when the journey is delivered through hosted pages.

If you omit context.config.delivery, then the API rejects the request with a 400 error. Sample v2 start request:

JSON

{
  "resourceId": "your-journey-resourceId@latest",
  "context": {
    "config": {
      "delivery": "api"
    },
    "subject": {
      "identity": {
        "firstName": "Jane",
        "lastNames": ["Doe"],
        "dateOfBirth": "1992-10-01"
      }
    }
  }
}

The context.subject prefill structure is unchanged from v1. Only the resourceId and context.config.delivery fields differ. The start request fields are:

Field	Required	Description
`resourceId`	Yes	The journey to start, in the `id@version` format. Use `@latest` for the most recent published version.
`context`	Yes	The container for the journey configuration and prefill data.
`context.config.delivery`	Yes	How the journey is delivered: `api` or `page`.
`context.subject`	No	Prefill data for the journey, using the same identity structure as v1.

Handle the asynchronous response

V1 supported both synchronous and asynchronous execution, selected with a config option. In synchronous mode, the start request waited while the journey was set up and returned results inline. V2 is asynchronous only. The start request returns immediately with an instanceId, and modules run in the background. Because processing continues after the response, you must poll for completion:

Poll POST /journey/state/fetch to check the journey status. Use a base interval of 10 seconds and apply backoff on errors.
Keep polling while the status is InProgress.
Stop polling when the status changes to Completed or Error, then read the results.

A successful interaction/submit response confirms that the API accepted your data. It does not mean processing has finished. Modules continue to run in the background, so you must still poll state/fetch for the final result.

For fully prefilled journeys, modules might already be complete by the time you first poll state/fetch.

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.

Interaction types

A v2 journey uses three types of interaction:

Start interaction: Validates the prefill data you send in the POST /journey/start request. It has no user interface, so you do not fetch or submit it like a standard interaction.
Standard interaction: Collects domain elements, such as name and date of birth, through API calls.
End interaction: Displays the outcome at the end of the journey. It collects no data.

Interaction nodes are required in v2 journeys. A journey with no interaction nodes does not run on v2. Because v1 journeys are not compatible with v2, a business user must create a new v2 journey that includes interaction nodes in the GBG GO platform before you migrate.

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

Prefill and submission behaviour

V2 changes how prefill data and partial submissions are handled:

Auto-advancement: If prefill provides all the data an interaction needs, then the interaction advances automatically without a submit. For a fully prefilled journey, modules can start immediately after journey/start.
Partial submission: You can submit domain elements in pieces. The interaction stays active until you provide all required elements.
Stricter validation: V2 validates prefill data for all delivery types. V1 only validated prefill for page delivery. If prefill worked in v1 but fails in v2, then check the domain elements the journey collects.

Two validation rules apply to each submit:

If a required domain element is missing, then the API rejects the whole submit with a 400 error.
If an optional domain element is invalid, then the API silently strips it and the submit succeeds.

Why you poll for completion

Within each journey segment, modules run in parallel rather than one after another. For example, a document check, a face match, and an email check can all run at the same time after you submit the required data. The journey waits for all parallel modules in a segment to finish before it evaluates the outcome and advances. This is why you must poll state/fetch: results are not returned inline, and you cannot know when every module has finished without checking the status. Parallel processing is automatic. You do not configure it, and it makes v2 journeys faster than v1, which ran modules one after another.

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:

Read the overall journey outcome from the context.process.result object. This is the recommended way to get results in v2.
Per-step detail is 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": "resourceId is required",
      "action": "Please provide resourceId (e.g., 'your-journey-resourceId@latest')"
    }
  ]
}

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

Error responses include an X-Request-ID header. This value identifies your specific request in GBG’s logs, so quote it when you contact GBG support about a failed request.

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.

Common error codes

The following error codes appear most often during migration:

HTTP status	Code	Name	Meaning	Action
400	4001	`INVALID_REQUEST`	Malformed request body	Check that your JSON matches the v2 contract.
400	4002	`MISSING_FIELD`	Required data is missing	Check the domain elements the journey collects and add `context.config.delivery`.
401	2001	`UNAUTHORIZED`	Token is invalid, expired, or lacks permissions	Refresh your token and check your account permissions.
403	2002	`FORBIDDEN`	The account lacks the required permissions	Check your account permissions.
404	4004	`NOT_FOUND`	The journey or delivery was not found	Verify your `instanceId` or `resourceId`.
500	5001	`UNKNOWN`	Internal server error	Retry with backoff and save the `X-Request-ID`.
503	5005	`SERVICE_UNAVAILABLE`	A downstream service is unavailable	Retry with backoff.

For more details, see Error handling.

Migration checklist

Before you change your integration, GBG completes these steps for you:

Assign journey permissions: GBG assigns the journey permissions to your API client.
Prepare the journey: A business user creates a new v2 journey with interaction nodes and publishes it in the GBG GO platform. You cannot migrate an existing v1 journey to v2.

Confirm these steps are complete with your GBG contact before you start. Then use the following checklist to track your own integration changes:

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.

Update the journey start request

Keep identifying the journey with resourceId in the id@version format, the same as v1. Add context.config.delivery, set to api for API-driven journeys or page for hosted journeys. Omitting the field returns a 400 error.

Handle async journey start

Update your /journey/start integration to handle the 201 response with instanceId. Poll POST /journey/state/fetch while the status is InProgress, and read the results when it changes to Completed or Error.

Confirm your journey is ready

Confirm with your GBG contact that your new v2 journey includes interaction nodes, the journey is published, and your API client has the journey permissions. A journey with no interaction nodes does not run on v2.

Retest your prefill data

V2 validates prefill for all delivery types, so prefill that worked in v1 might now be rejected. Test your prefill data against the domain elements the journey collects.

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.

FAQ

We rely on synchronous behaviour. What changes in v2?

V2 is asynchronous. The start request returns immediately with an instanceId, and modules run in the background. You must add polling logic that calls POST /journey/state/fetch until the status changes to Completed or Error.

Do we need a new token for v2?

No. You use the same tokens and the same token flow as v1. However, your API client must have the journey permissions assigned before you migrate. If they are not assigned, then v2 rejects your requests with a 401 or 403 error.

Does our prefill data format change?

No. The context.subject structure is identical to v1. The only new field in the start request is context.config.delivery, which is now required.

Our prefill worked in v1 but fails in v2. Why?

V2 validates prefill data for all delivery types. V1 only validated prefill for page delivery. Check the domain elements the journey collects to confirm your prefill data matches what the journey expects.

Do I need interaction nodes in my journey?

Yes. Interaction nodes are required in v2 journeys. A journey with no interaction nodes does not run on v2. V1 journeys are not compatible with v2, so a business user must create a new v2 journey that includes interaction nodes in the GBG GO platform before you migrate.Use this table to check whether your journey runs on v2:

Scenario	Runs on v2?	What you need
API-driven journey, all data prefilled at start	Yes	Interaction nodes are in the journey but auto-advance when the collected elements are satisfied.
API-driven journey, data submitted through API calls	Yes	`interaction/fetch` tells you what to submit.
V2 journey with no interaction nodes	No	A business user must add interaction nodes to the v2 journey in the GBG GO platform.
Existing v1 journey	No	V1 journeys are not compatible with v2. A business user must create a new v2 journey.
V1 journey still running on v1	Yes	No changes are needed until you migrate. You can run v1 and v2 in parallel during cutover.

Does v2 support the intent field, such as Save or Complete?

No. In v2, you submit domain elements directly. A partial submit keeps the interaction active, and the journey advances automatically when all required domain elements are submitted.

Can we run v1 and v2 in parallel during cutover?

Yes. V1 and v2 use different URL prefixes and separate state, so there are no conflicts. Running both in parallel is recommended for a staged migration.

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.

​What changed in v2

​What stays the same

​Base URL changes

​Authentication changes

​Journey permissions

​API endpoint changes

​Journey endpoints

​Interaction endpoints (replace task endpoints)

​Deprecated v1 task endpoints

​Journey start request changes

​Identify the journey with resourceId

​Specify the delivery type

​Handle the asynchronous response

​From tasks to interactions

​How tasks worked in v1

​How interactions work in v2

​Interaction types

​Key differences

​Prefill and submission behaviour

​Why you poll for completion

​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

​Common error codes

​Migration checklist

​FAQ

​Next steps

What changed in v2

What stays the same

Base URL changes

Authentication changes

Journey permissions

API endpoint changes

Journey endpoints

Interaction endpoints (replace task endpoints)

Deprecated v1 task endpoints

Journey start request changes

Identify the journey with resourceId

Specify the delivery type

Handle the asynchronous response

From tasks to interactions

How tasks worked in v1

How interactions work in v2

Interaction types

Key differences

Prefill and submission behaviour

Why you poll for completion

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

Common error codes

Migration checklist

FAQ

Next steps