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.

Each interaction in a journey requires specific data to be submitted before the journey can progress. This data is structured around domain elements, which are units of identity data such as FullName, PrimaryDocument, or DateOfBirth. Use the Submit interaction (/journey/interaction/submit) endpoint to submit collected data for the current interaction.

​
When to submit interaction data

You need to submit interaction data when:
  • The end user has provided input for one or more domain elements listed in the fetch interaction response.
  • You want to advance the journey to the next interaction or to completion.
  • You are submitting a partial set of domain elements and plan to submit the remaining elements in a subsequent call.

​
Before getting started

Before sending the request, make sure you have the access token obtained in Step 1: Authenticate for API authentication.

​
Submit interaction data

Send a POST request to the /journey/interaction/submit endpoint:
BASH
 curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/interaction/submit \
  --header 'Authorization: Bearer your_end_user_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
    "interactionId": "grn:::gbg:design:interaction:identity-form@latest",
    "participants": [
      { "domainElementId": "FullName" },
      { "domainElementId": "DateOfBirth" },
      { "domainElementId": "CurrentAddress" }
    ],
    "context": {
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01",
          "currentAddress": {
            "lines": ["12 Example Street"],
            "locality": "London",
            "postalCode": "SW1A 1AA",
            "country": "GB"
          }
        }
      }
    }
  }'

​
Request body fields

FieldRequiredDescription
instanceIdYesThe journey instance ID returned when you started the journey.
interactionIdYesThe interaction ID returned in the fetch interaction response.
contextNoThe collected domain elements, structured under subject.
participantsNoList of domain element identifiers being submitted in this call. Used to indicate which domain elements are included, particularly for partial submissions.
Partial submissions are supported. You can submit a subset of the required domain elements and call this endpoint again with the remaining elements. Use the outstanding array in the fetch interaction response to track which domain elements still need to be submitted.

​
Successful response

If your request is valid, the API returns a 200 OK response:
JSON
{
  "status": "success"
}
After a successful submission, the platform advances the journey asynchronously. Resume polling /journey/interaction/fetch to discover the next interaction. Repeat this loop until journey.status is no longer InProgress.

​
How to determine field structure for submission

The fetch interaction response from Step 3 tells you which domain elements are required and which are optional for the current interaction. Use the collects[] and outstanding[] arrays to identify what data is needed. To understand the full field structure and data types for each domain element, retrieve the schema for your journey from Dashboard in the GBG GO platform. Follow the steps below to access the schema:
  1. Log in to the GBG GO platform.
  2. Locate your published journey.
  3. Click Dashboard.
  4. Click the Actions list for your specific environment.
  5. Click View schema.
The schema defines the required fields, expected data types, format restrictions, and structure for the context.subject object. Use it alongside the fetch interaction response to construct your submission with the correct fields and format. For a full reference of all possible fields and data types, see User data input schema.
The schema may change when a journey is updated. Always retrieve the latest schema after publishing a new version of your journey.

​
FAQ

In the v2 API, documents are submitted inside context.subject.documents as part of an interaction submission. Each document object includes a base64-encoded image for each side and a type field.Example: Submitting the front of a primary document:
JSON
{
  "instanceId": "your-instance-id",
  "interactionId": "your-interaction-id",
  "participants": [
    { "domainElementId": "PrimaryDocument" }
  ],
  "context": {
    "subject": {
      "documents": [
        {
          "side1Image": "<base64-encoded-image>",
          "side2Image": "",
          "type": "Primary"
        }
      ]
    }
  }
}
Field reference:
FieldDescription
side1ImageBase64-encoded image of the front of the document.
side2ImageBase64-encoded image of the back of the document. Leave as an empty string if not applicable.
typeThe document type. Use "Primary" for the main identity document.

​
Submitting a selfie

Biometric data such as a selfie is submitted separately inside context.subject.biometrics:
{
  "instanceId": "your-instance-id",
  "interactionId": "your-interaction-id",
  "participants": [
    { "domainElementId": "Selfie" }
  ],
  "context": {
    "subject": {
      "biometrics": [
        {
          "selfieImage": "<base64-encoded-image>"
        }
      ]
    }
  }
}
Documents and biometrics must be placed inside context.subject. Placing them outside subject causes the request to fail.
Partial submissions are supported. You can submit documents and biometrics in separate calls to the same interaction. Use the outstanding field in the interaction fetch response to track which domain elements still need to be provided.
Identity data is submitted inside context.subject.identity as part of an interaction submission. You only need to include the fields relevant to your journey’s requirements.

​
Submitting a Social Security Number (SSN)

SSN is submitted as an entry in the idNumbers array with a type of "ssn":
JSON
{
  "instanceId": "your-instance-id",
  "interactionId": "your-interaction-id",
  "participants": [
    { "domainElementId": "SSN" }
  ],
  "context": {
    "subject": {
      "identity": {
        "idNumbers": [
          {
            "idNumber": "123-45-6789",
            "type": "ssn"
          }
        ]
      }
    }
  }
}

​
Submitting date of birth only

The response below shows how to submit just the date of birth if that’s the only required field for your journey.
JSON
{
  "instanceId": "your-instance-id",
  "interactionId": "your-interaction-id",
  "participants": [
    { "domainElementId": "DateOfBirth" }
  ],
  "context": {
    "subject": {
      "identity": {
        "dateOfBirth": "1990-01-01"
      }
    }
  }
}

​
Submitting partial identity data

Partial submissions are supported for identity data. This means you can submit a subset of the required identity fields in one API call, and then submit the remaining fields in subsequent calls as you collect them from the end user. Use the outstanding array in the fetch interaction response to track which identity fields still need to be submitted.For example, if your journey requires FullName, DateOfBirth, and PrimaryDocument, you could first submit just DateOfBirth, then check the next fetch interaction response to see that FullName and PrimaryDocument are still outstanding, and submit those in the next call. Refer to partial prefill mode in Step 2: Start a journey for how to submit partial identity data when starting a journey.

​
Next step

Go to Step 5: Fetch journey state to check whether the journey has completed or if more interactions remain.