Step 4: Fetch journey state - GBG Documentation

At any point during a journey, you can check the overall journey status and results. For Hosted journeys, your backend polls this endpoint to detect when the end user has completed the verification experience on the hosted pages.

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": "P7U7Licy40cLZiENe8MrsL"
  }'

Request body fields

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

Journey pending response:

If the end user has not yet completed the hosted journey, the response contains:

JSON

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

Journey completed response:

Once the end user completes the hosted journey:

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 end user has not yet completed the hosted journey. Continue polling.
`Completed`	The hosted 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 sharing the instanceUrl with the end user.
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 5 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`.

Using webhooks as an alternative

Instead of polling, you can configure webhooks to receive real-time notifications when a journey completes or fails. This eliminates the need for repeated API calls and allows your backend to react immediately to status changes. To set up webhooks, refer to the Webhook module guide.

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.

​What you need

​Fetch journey state

​Request body fields

​Journey pending response:

​Journey completed response:

​Response fields

​Journey lifecycle states

​Polling for completion

​Recommended polling settings

​Using webhooks as an alternative

​Best practices