Step 5: Fetch journey state

Poll the journey status to detect completion and retrieve verification results.

At any point during a journey, you can check the overall journey status and results. This is especially useful after the final interaction is submitted, when you need to detect completion and retrieve verification outcomes.

What you need

Before sending the request, make sure you have:

• Access token: Obtained in Step 1: Authenticate.
• Instance ID: The instanceId returned when you started the journey.

Fetch journey state

Send a POST request to the /journey/state/fetch endpoint:

BASH

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/state/fetch \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu"
  }'

Request body fields

Field	Required	Description
instanceId	Yes	The journey instance ID returned when you started the journey.

Journey pending response:

If the journey is still in progress, then the response contains:

JSON

{
  "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
  "status": "InProgress",
  "context": {
    "process": {
      "journey": {
        "name": "Journey Name",
        "startedAt": "2026-03-16T23:56:04.097Z",
        "id": "9dcd95e06495ec32c9ad149283a935548e4a380461b9ee6981af0fef5c70c8c3",
        "version": "5f7yigc4"
      },
      "instance": {
        "id": "Pq_hhIX6-sHUy9FLSDzPLu",
        "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu"
      },
      "steps": []
    },
    "subject": {},
    "result": {
      "status": "pending",
      "advice": {}
    }
  }
}

Journey completed response:

Once the journey completes, the system returns a response similar to the following:

JSON

{
  "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
  "status": "Completed",
  "context": {
    "process": {
      "journey": {
        "endedAt": "2026-03-16T23:57:38.417Z",
        "durationMilliSec": 94320,
        "terminateInteraction": {
          "grId": "grn:::gbg:design:interaction:end@latest",
          "resource": {
            "type": "interaction",
            "data": {
              "pages": [
                {
                  "cards": [
                    {
                      "id": "AllDoneCard"
                    }
                  ],
                  "id": "pagesForEnd"
                }
              ]
            },
            "id": "end",
            "name": "interactionEnd",
            "version": "latest"
          },
          "collects": [],
          "consumes": []
        },
        "id": "9dcd95e06495ec32c9ad149283a935548e4a380461b9ee6981af0fef5c70c8c3",
        "version": "5f7yigc4",
        "name": "Age verification",
        "startedAt": "2026-03-16T23:56:04.097Z"
      },
      "instance": {
        "id": "Pq_hhIX6-sHUy9FLSDzPLu",
        "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu"
      },
      "steps": [
        {
          "nodeId": "mp586xkhweua5v4z5n",
          "result": {
            "status": "complete",
            "note": {
              "expectid_age": {
                "id_number": "6554532688"
              }
            },
            "advice": {
              "trust_usa_risk_capabilities": [],
              "age_restricted_capabilities": [],
              "subject_risk_capabilities": [],
              "address_risk_capabilities": [],
              "ssn_risk_capabilities": [],
              "alert_list_capabilities": [],
              "match_result_capabilities": [],
              "trust_usa_result_capabilities": [],
              "name_risk_capabilities": [],
              "dob_risk_capabilities": [],
              "acceptance_result_capabilities": [],
              "age_result_capabilities": [
                "resultcode.confirm.age"
              ]
            },
            "outcome": "Of Age"
          },
          "process": {}
        }
      ]
    },
    "subject": {
      "identity": {
        "dateOfBirth": "1982-09-27",
        "firstName": "John",
        "lastNames": [
          "Doe"
        ],
        "currentAddress": {
          "postalCode": "900010",
          "country": "US",
          "lines": [
            "New Orleans, Louisiana, U.S."
          ],
          "locality": "New Orleans"
        }
      }
    },
    "result": {
      "status": "complete",
      "advice": {}
    }
  }
}

Response fields

Field	Description
instanceId	The journey instance identifier.
status	Current journey status: InProgress, Completed, or Failed.
context.process.journey.name	The name of the journey.
context.process.journey.startedAt	The ISO 8601 timestamp of when the journey started.
context.process.journey.endedAt	The ISO 8601 timestamp of when the journey completed. Present only when the journey has finished.
context.process.journey.durationMilliSec	The total journey duration in milliseconds. Present only when the journey has finished.
context.process.journey.id	The internal journey definition identifier.
context.process.journey.version	The version of the journey that was started.
context.process.journey.terminateInteraction	The terminating interaction shown to the user when the journey ends, including its grId, resource definition, and any collects and consumes arrays.
context.process.instance.id	The journey instance identifier (matches instanceId).
context.process.steps	Array of steps executed so far. Empty while the journey is in progress. Each step includes a nodeId, a result (with status, note, advice, and outcome), and a process object.
context.subject.identity	The identity data collected during the journey, such as firstName, lastNames, dateOfBirth, and currentAddress. Empty object until the journey completes.
context.result.status	The verification result status: pending, complete, or failed.
context.result.advice	The verification advice returned on completion. Empty object until the journey completes.

Journey lifecycle states

Status	Description
InProgress	The journey is still in progress. Continue polling.
Completed	The journey has finished successfully. Verification results are available.
Failed	The journey encountered an unrecoverable error during execution.

Polling for completion

Poll the state fetch endpoint at regular intervals until the journey completes:

• Begin polling after submitting the final interaction data.
• Stop polling when status changes to Completed or Failed.

Recommended polling settings

Setting	Value	Description
Base interval	10s	Time between polling calls.
Error backoff	+5s	Add five seconds per consecutive error.
Max error retries	30	Stop polling after 30 consecutive failures.
Reset on success	Yes	Revert to base interval after a successful fetch.
Stop condition	Status	Stop when journey status is no longer InProgress.

Best practices

• Do not share your access token with the frontend. All polling should be done from your backend server.
• Handle the Failed status gracefully. Inspect the response for error details and determine whether the journey should be retried or escalated.

FAQ

What is the difference between sync and async journey execution?

In the v2 API, all journey execution is asynchronous. There is no synchronous mode.

When you start a journey, the API returns an instanceId immediately. Backend modules such as document verification, face matching, data checks process in the background.

To track progress, you poll the /journey/interaction/fetch endpoint to discover when the next interaction is available, or poll /journey/state/fetch to check the overall journey status.

The recommended polling approach is to call the fetch endpoint at a base interval of 10 seconds, apply backoff on errors, and stop when the journey status changes from InProgress to either Completed or Failed.

If you are migrating from v1: the async: true flag was a v1-specific concept. In v2, async behaviour is the default and does not need to be specified.