Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt

Use this file to discover all available pages before exploring further.

Fetch the current interaction to find out what data is needed from the end user. The fetch response replaces the separate “retrieve tasks” and “manage schemas” steps from the v1 API. It returns the interaction definition, required domain elements, and UI structure in a single call.

​
Before getting started

Before sending the request, make sure you have:
  • Access token: Obtained in Step 1: Authenticate for API authentication.
  • Instance ID: The instanceId returned when you started the journey.

​
Fetch the interaction

Send a POST request to the /journey/interaction/fetch endpoint:
BASH
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/interaction/fetch \
  --header 'Authorization: Bearer your_end_user_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.

​
Successful response

If an interaction is available, the API returns a 200 OK response:
JSON
{
  "instanceId": "PiIuACmx8Q8R7qPnAkLAqBAT",
  "interactionId": "grn:::gbg:design:interaction:identity-form@latest",
  "journey": {
    "status": "InProgress"
  },
  "interaction": {
    "grId": "grn:::gbg:design:interaction:identity-form@latest",
    "resource": {
      "id": "identity-form",
      "name": "Identity Verification",
      "type": "interaction",
      "version": "latest",
      "data": {
        "pages": [
          {
            "id": "personal_details",
            "label": "Personal Details",
            "cards": [
              { "id": "NameCard" },
              { "id": "DateOfBirthCard" }
            ]
          },
          {
            "id": "contact_details",
            "label": "Contact Details",
            "cards": [
              { "id": "EmailCardPersonalEmail" },
              { "id": "PhoneCardMobilePhone" }
            ]
          },
          {
            "id": "document_capture",
            "label": "Document Capture",
            "cards": [
              { "id": "DocumentCard" }
            ]
          }
        ]
      }
    },
    "collects": [
      { "ref": "FullName", "spec": "required" },
      { "ref": "DateOfBirth", "spec": "required" },
      { "ref": "PrimaryDocument", "spec": "required" },
      { "ref": "PersonalEmail", "spec": "optional" },
      { "ref": "MobilePhone", "spec": "optional" }
    ],
    "consumes": []
  },
  "context": {},
  "outstanding": [
    "FullName",
    "DateOfBirth",
    "PrimaryDocument"
  ]
}

​
Response fields

FieldDescription
interactionIdUnique ID for this interaction. Include it when submitting.
journey.statusCurrent journey status: InProgress, Completed, or Failed.
interaction.resourceDescribes the UI to render — pages, cards, and their configuration.
interaction.collects[]Domain elements this interaction gathers from the user. Each entry has a ref (domain element catalog ID, for example, FullName, PrimaryDocument, Selfie) and a spec (required, optional, or conditional).
interaction.consumes[]Domain elements this interaction displays to the user as read-only context.
contextPartial journey context relevant to this interaction.
outstandingDomain element catalog IDs not yet collected. Tracks partial submission progress.
If backend modules, for example, document verification or face matching are still executing, no interaction will be available yet. Poll this endpoint until an interactionId appears or until journey.status changes away from InProgress.

​
Understanding the response

Use the fetch interaction response to drive your end-user interface and data collection. The response provides everything you need to build your frontend forms the page structure, the cards to render, which domain elements to collect, and whether each element is required or optional.

​
Pages and cards

The interaction.resource.data.pages array describes the UI layout. Each page contains cards, and each card corresponds to a domain element collection component (for example, NameCard collects FullName, DocumentCard collects PrimaryDocument). Use this structure to guide how you build your frontend — for example, render each page as a step in a multi-step form, and map each card to the appropriate input component for the domain element it collects.

​
Collects and outstanding

The collects array lists every domain element this interaction is designed to gather. The outstanding array lists only those elements that have not yet been submitted. If you are using partial submissions, the outstanding array shrinks as you submit data. Use outstanding to determine which form fields still need to be displayed or highlighted to the user.

​
Spec values

Each domain element in collects has a spec that indicates whether it is required:
SpecMeaning
requiredThe domain element must be submitted for the interaction to complete.
optionalThe domain element can be submitted but is not mandatory.
conditionalThe requirement depends on the journey context.

​
Polling for interactions

The journey API operates asynchronously. After starting a journey or submitting data, backend modules, such as document verification or face matching, may need time to process before the next interaction is available. If no interaction is available yet, poll this endpoint until an interactionId appears in the response or until journey.status changes from InProgress.

​
Building your frontend from the response

The fetch interaction response is designed to give you everything you need to dynamically build your data collection UI:
  1. Map pages to screens or steps: Each object in the pages array represents a logical grouping of fields. Render each page as a separate screen, tab, or step in a multi-step form.
  2. Map cards to input components: Each card within a page corresponds to a specific data collection component. Use the card id to determine which input fields to render, for example, NameCard maps to first name and last name fields, DateOfBirthCard maps to a date picker.
  3. Use collects to validate requirements: Check the spec value for each domain element to determine whether a field is required, optional, or conditional. Apply appropriate validation rules in your frontend based on these values.
  4. Use outstanding to track progress: After each partial submission, call /journey/interaction/fetch again. The outstanding array tells you which domain elements still need to be collected, allowing you to update your UI accordingly.
By building your frontend dynamically from the fetch interaction response, your UI automatically adapts when journey configurations change without requiring code updates.

​
FAQ

These are the core building blocks of the GBG GO platform:
  • Journey: A journey is a structured workflow that guides an end user through verification steps such as identity checks, document processing, and fraud screening.
  • Module: A module is a functional component within a journey that performs a specific verification task. Examples include Document Classification, Document Authentication, Data Verification, Age Verification, and Facematch. Each module can have one or more variants, which are different configurations tailored to specific regions, compliance rules, or business requirements, for example, “US Data Verification.”
  • Capability: Capabilities are the underlying services that modules use to perform their tasks. For example, the Document Authentication module relies on the Document Authentication capability, which provides the core logic for verifying document authenticity.
  • Interaction: An interaction is a step in the journey where the platform collects information from the end user. When you fetch an interaction, the response describes which data elements are needed (the collects array), which are required or optional (the spec field), and which have already been provided (the outstanding array). In the v2 API, interactions replace the v1 task-based model.
  • Evaluation: An evaluation is a decision-making step in the journey where the platform determines an outcome, such as accept, reject, or refer for manual review, based on the results of the preceding verification modules.