Skip to main content
This quickstart guides you through your first API-first integration with GBG GO. Authenticate, start a journey, fetch the first interaction, submit data, and poll for completion.

​
Before you start

Before running this quickstart, make sure you have:
  • A published journey with the journey resource ID and version number copied from the GBG GO dashboard.
  • An API client created in the Account management portal, which provides the credentials you use to authenticate:
    • client_id: Your unique API client identifier.
    • client_secret: Your secret key for API authentication.
    For instructions on creating an API client, see Manage API clients.
  • A tool capable of making HTTP requests, for example, curl or Postman.
API client credentials are different from your GBG GO platform login. They are specifically for programmatic access.

​
Step 1: Set up your journey

Before making API calls, you need a published journey with the Age Verification module. Follow the steps in Option 2: Create a journey from scratch of the Platform quickstart to add the Age Verification module to your journey and publish it. Once your journey is published to preview, copy the Resource ID and version from the Dashboard. You need these to start the journey through the API.

​
Step 2: Authenticate

Send a POST request to get your Bearer token:
cURL
curl --request POST \
  --url https://api.auth.gbgplc.com/as/token.oauth2 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id=your-client-id' \
  --data 'client_secret=your-client-secret' \
  --data 'scope=gbg.token'
A successful response returns an access token:
JSON
{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 3600
}
Use it to authenticate subsequent API calls by including it in the Authorization header.
Store the access_token securely. Don’t share it in emails, chat messages, client-side code, or publicly accessible locations.

​
Step 3: Start a journey

Use your access token, journey resource ID and version to start a journey instance. Set context.config.delivery to "api" for API-first journeys.

​
Non-prefill mode

Start with an empty subject. The end user provides all data through interactions:
cURL
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/start \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "resourceId": "97c8b0c5272ba450c48899cc78f6e3f3ba89b5d131c42f7ea972588bd8213b3e@y5z6bj7o",
    "context": {
      "config": { "delivery": "api" },
      "subject": {}
    }
  }'
The @5z6bj7o suffix in the resource ID represents the journey version. Replace it with your specific version for production integrations. Using @latest can introduce a small delay in processing. Usually less than 10 seconds.

​
Partial pre-fill mode

If you already have some user data, include it in context.subject. Remove the corresponding domain elements from the Interaction Group panel so the journey doesn’t collect them again:
cURL
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/start \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "resourceId": "97c8b0c5272ba450c48899cc78f6e3f3ba89b5d131c42f7ea972588bd8213b3e@y5z6bj7o",
    "context": {
      "config": { "delivery": "api" },
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01"
        }
      }
    }
  }'
A successful response returns an instanceId:
JSON
{
  "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
  "status": "started",
  "message": "Journey Pq_hhIX6-sHUy9FLSDzPLu started successfully"
}
Save the instanceId — you need it for all subsequent API calls in this journey.
Replace @latest with your specific journey version for production integrations. Using @latest can introduce a small delay in processing.

​
Step 4: Fetch the interaction

Poll /journey/interaction/fetch to retrieve the current interaction and discover what data the end user must provide:
cURL
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/interaction/fetch \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu"
  }'
The response includes the interaction definition and the domain elements that need to be collected:
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"
  ]
}
Use this information to build your front-end data collection forms and guide end users through the required steps. To find out more about the response, see Understanding the response.
FieldDescription
instanceIdIdentifier for the journey instance created during journey start.
interactionIdGRN of the current interaction. Use this when submitting data back to the platform.
journey.statusCurrent status of the journey, for example, InProgress or Completed.
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.collectsDomain elements the interaction is configured to collect. Each entry has a ref, a spec (required or optional), 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 or optional for the end user to provide.
interaction.collects[].parentSpecPresent only when the parent element is itself optional. Indicates the whole group can be skipped, but if the end user engages with it, the component’s spec still applies.
interaction.consumesDomain elements the interaction reads but does not collect. Empty when the interaction only collects data.
outstandingDomain elements that still need to be submitted before the journey can progress. Use this to decide what to ask the end user for next.
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.
If no interactionId is returned yet, the platform is still processing. Keep polling until an interactionId appears or journey.status changes from InProgress.

​
Step 5: Submit interaction data

Once you’ve collected data from the end user, submit it using the interactionId from the fetch response:
cURL
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/interaction/submit \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
    "interactionId": "grn:::gbg:design:interaction:identity-form@latest",
    "participants": [
      { "domainElementId": "FullName" },
      { "domainElementId": "DateOfBirth" }
    ],
    "context": {
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Doe"],
          "dateOfBirth": "1992-10-01"
        }
      }
    }
  }'
A successful response:
JSON
{
  "status": "success"
}
Now, the GO platform processes the submitted data. Poll /journey/interaction/fetch again to get the next interaction or check if the journey is complete.
You don’t need to submit all required domain elements at once. Submit a subset and call the submit endpoint again with the remaining elements. Check the outstanding field in the fetch response to see what still needs to be provided.

​
Step 6: Fetch journey state

Once all interactions are submitted, poll /journey/state/fetch to detect completion and retrieve verification results:
cURL
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"
  }'
Poll until status is no longer InProgress:
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": {}
    }
  }
}
In the response above, John Doe’s age is verified using the Age Verification module. The result is “Of Age,” and the journey is complete. The response also includes the full subject data and module result details. Next, view verification results, data and outcomes in the Investigation portal in the GBG GO dashboard. Based on the status field, take appropriate actions:
StatusMeaning
InProgressThe journey is still active. Retrieve remaining tasks.
CompletedThe journey is done. No further action is needed.
FailedThe journey encountered an error. Review previous steps or retry.

​
Next steps