Step 4: 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. 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.