Skip to main content
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": "Pq_hhIX6-sHUy9FLSDzPLu",
  "interactionId": "grn:::gbg:design:interaction:segment1@latest",
  "journey": {
    "status": "InProgress"
  },
  "interaction": {
    "grId": "grn:::gbg:design:interaction:segment1@latest",
    "resource": {
      "id": "segment1",
      "name": "segment1",
      "version": "latest",
      "type": "interaction",
      "data": {
        "pages": [
          {
            "id": "personal_details",
            "label": "Personal details",
            "cards": [
              { "id": "NameCard" },
              { "id": "DateOfBirthCard" },
              { "id": "IdentifierCardSSN" },
              { "id": "ControlCard" }
            ]
          },
          {
            "id": "contact_details",
            "label": "Contact details",
            "cards": [
              { "id": "EmailCardPersonalEmail" },
              { "id": "PhoneCardMobilePhone" },
              { "id": "ControlCard" }
            ]
          },
          {
            "id": "address_details",
            "label": "Address details",
            "cards": [
              {
                "id": "AddressCard",
                "config": {
                  "secrets": {
                    "loqateApiKey": {
                      "value": "WJ28-WP43-WG34-YD87"
                    }
                  }
                }
              },
              { "id": "ControlCard" }
            ]
          },
          {
            "id": "previous_addresses",
            "label": "Previous Addresses",
            "cards": [
              { "id": "PreviousAddressesCard" },
              { "id": "ControlCard" }
            ]
          }
        ]
      }
    },
    "collects": [
      { "ref": "FullName/firstName", "spec": "required" },
      { "ref": "FullName/middleNames", "spec": "optional" },
      { "ref": "FullName/lastNames", "spec": "required" },
      { "ref": "FullName/title", "spec": "optional" },
      { "ref": "DateOfBirth", "spec": "required" },
      { "ref": "SSN", "spec": "optional" },
      { "ref": "PersonalEmail/email", "spec": "required", "parentSpec": "optional" },
      { "ref": "MobilePhone/number", "spec": "required", "parentSpec": "optional" },
      { "ref": "CurrentAddress/lines", "spec": "optional" },
      { "ref": "CurrentAddress/addressString", "spec": "optional" },
      { "ref": "CurrentAddress/premise", "spec": "optional" },
      { "ref": "CurrentAddress/building", "spec": "optional" },
      { "ref": "CurrentAddress/subBuilding", "spec": "optional" },
      { "ref": "CurrentAddress/thoroughfare", "spec": "optional" },
      { "ref": "CurrentAddress/dependentThoroughfare", "spec": "optional" },
      { "ref": "CurrentAddress/locality", "spec": "optional" },
      { "ref": "CurrentAddress/dependentLocality", "spec": "optional" },
      { "ref": "CurrentAddress/doubleDependentLocality", "spec": "optional" },
      { "ref": "CurrentAddress/postalCode", "spec": "optional" },
      { "ref": "CurrentAddress/postBox", "spec": "optional" },
      { "ref": "CurrentAddress/country", "spec": "optional" },
      { "ref": "CurrentAddress/superAdministrativeArea", "spec": "optional" },
      { "ref": "CurrentAddress/administrativeArea", "spec": "optional" },
      { "ref": "CurrentAddress/subAdministrativeArea", "spec": "optional" },
      { "ref": "CurrentAddress/organization", "spec": "optional" },
      { "ref": "CurrentAddress/location", "spec": "optional" },
      { "ref": "PreviousAddresses", "spec": "optional" }
    ],
    "consumes": []
  },
  "outstanding": [
    "FullName/firstName",
    "FullName/lastNames",
    "DateOfBirth"
  ]
}
Refs that contain a slash, for example, FullName/firstName and MobilePhone/number, are granular domain elements. They request a specific component of a larger domain element instead of the whole thing. Use the spec field to see which components are required versus optional.

​
Response fields

FieldDescription
instanceIdIdentifier for the journey instance. Include it in every subsequent API call for this journey.
interactionIdGRN of the current interaction. Include it when submitting.
journey.statusCurrent journey status: InProgress, Completed, or Failed.
interaction.grIdFully qualified GRN of the interaction resource.
interaction.resourceMetadata about the interaction, including its id, name, version, and type.
interaction.resource.data.pagesOrdered list of pages the end user will see. Each page has an id, label, and a list of cards.
interaction.resource.data.pages[].cardsVisual groupings of input fields shown on a page. Each card references a card definition by id, for example, NameCard or AddressCard, and can carry per-card config, such as supplier API keys.
interaction.collects[]Domain elements this interaction gathers from the user. Each entry has a ref, a spec (required, optional, or conditional), and optionally a parentSpec.
interaction.collects[].refIdentifier for the domain element or granular domain element. Refs with a slash, for example, FullName/firstName, target a specific component of a larger element.
interaction.collects[].specWhether this component is required, optional, or conditional for the end user to provide.
interaction.collects[].parentSpecPresent only when the parent element is itself optional or conditional. Indicates the whole group can be skipped, but if the end user engages with it, the component’s spec still applies.
interaction.consumes[]Domain elements this interaction displays to the user as read-only context.
outstandingDomain element identifiers 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. This include the page structure, cards to render, 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 the components of FullName, and AddressCard collects the components of CurrentAddress. 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 entry in collects has a spec that indicates whether it is required, and may also have a parentSpec when the parent domain element is itself optional or conditional:
FieldValueMeaning
specrequiredThe component must be submitted for the interaction to complete.
specoptionalThe component can be submitted but is not mandatory.
specconditionalThe requirement depends on the journey context.
parentSpecoptionalThe whole parent element can be skipped. If the end user engages with it, the component’s spec still applies.
parentSpecconditionalThe whole parent element is required only when journey context conditions are met. If engaged, the component’s spec still applies.
For example, PersonalEmail/email with spec: "required" and parentSpec: "optional" means: the end user can skip providing an email entirely, but if they start filling it in, the email itself must be valid.

​
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.