> ## 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.
# Step 3: Fetch interaction
> Retrieve the current interaction to discover what domain element data the end user must provide.
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](/docs/go-v2/developer-integration/execute-customer-journeys/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`](/docs/go-v2/api-reference/endpoint/fetch-interaction) endpoint:
```bash BASH theme={null}
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
| Field | Required | Description |
| ------------ | -------- | -------------------------------------------------------------- |
| `instanceId` | Yes | The journey instance ID returned when you started the journey. |
### Successful response
If an interaction is available, the API returns a `200 OK` response:
```json JSON expandable theme={null}
{
"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](/docs/go-v2/get-started/glossary#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
| Field | Description |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instanceId` | Identifier for the journey instance. Include it in every subsequent API call for this journey. |
| `interactionId` | GRN of the current interaction. Include it when submitting. |
| `journey.status` | Current journey status: `InProgress`, `Completed`, or `Failed`. |
| `interaction.grId` | Fully qualified GRN of the interaction resource. |
| `interaction.resource` | Metadata about the interaction, including its `id`, `name`, `version`, and `type`. |
| `interaction.resource.data.pages` | Ordered list of pages the end user will see. Each page has an `id`, `label`, and a list of `cards`. |
| `interaction.resource.data.pages[].cards` | Visual 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[].ref` | Identifier for the domain element or [granular domain element](/docs/go-v2/get-started/glossary#granular-domain-elements). Refs with a slash, for example, `FullName/firstName`, target a specific component of a larger element. |
| `interaction.collects[].spec` | Whether this component is `required`, `optional`, or `conditional` for the end user to provide. |
| `interaction.collects[].parentSpec` | Present 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. |
| `outstanding` | Domain 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:
| Field | Value | Meaning |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `spec` | `required` | The component must be submitted for the interaction to complete. |
| `spec` | `optional` | The component can be submitted but is not mandatory. |
| `spec` | `conditional` | The requirement depends on the journey context. |
| `parentSpec` | `optional` | The whole parent element can be skipped. If the end user engages with it, the component's `spec` still applies. |
| `parentSpec` | `conditional` | The 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.