Skip to main content
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:

​
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

FieldRequiredDescription
instanceIdYesThe 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

FieldDescription
instanceIdThe journey instance identifier.
statusCurrent journey status: InProgress, Completed, or Failed.
context.process.journey.nameThe name of the journey.
context.process.journey.startedAtThe ISO 8601 timestamp of when the journey started.
context.process.journey.endedAtThe ISO 8601 timestamp of when the journey completed. Present only when the journey has finished.
context.process.journey.durationMilliSecThe total journey duration in milliseconds. Present only when the journey has finished.
context.process.journey.idThe internal journey definition identifier.
context.process.journey.versionThe version of the journey that was started.
context.process.journey.terminateInteractionThe terminating interaction shown to the user when the journey ends, including its grId, resource definition, and any collects and consumes arrays.
context.process.instance.idThe journey instance identifier (matches instanceId).
context.process.stepsArray 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.identityThe identity data collected during the journey, such as firstName, lastNames, dateOfBirth, and currentAddress. Empty object until the journey completes.
context.result.statusThe verification result status: pending, complete, or failed.
context.result.adviceThe verification advice returned on completion. Empty object until the journey completes.

​
Journey lifecycle states

StatusDescription
InProgressThe journey is still in progress. Continue polling.
CompletedThe journey has finished successfully. Verification results are available.
FailedThe 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.
SettingValueDescription
Base interval10sTime between polling calls.
Error backoff+5sAdd five seconds per consecutive error.
Max error retries30Stop polling after 30 consecutive failures.
Reset on successYesRevert to base interval after a successful fetch.
Stop conditionStatusStop 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

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.