API-first integration quickstart

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.

Response field reference

Field	Description
`instanceId`	Identifier for the journey instance created during journey start.
`interactionId`	GRN of the current interaction. Use this when submitting data back to the platform.
`journey.status`	Current status of the journey, for example, `InProgress` or `Completed`.
`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 the interaction is configured to collect. Each entry has a `ref`, a `spec` (`required` or `optional`), and optionally a `parentSpec`.
`interaction.collects[].ref`	Identifier 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[].spec`	Whether this component is `required` or `optional` for the end user to provide.
`interaction.collects[].parentSpec`	Present 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.consumes`	Domain elements the interaction reads but does not collect. Empty when the interaction only collects data.
`outstanding`	Domain 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:

Status	Meaning
`InProgress`	The journey is still active. Retrieve remaining tasks.
`Completed`	The journey is done. No further action is needed.
`Failed`	The journey encountered an error. Review previous steps or retry.

Next steps

API usage guides: detailed step-by-step reference for each API call.
API reference: complete request and response definitions.
Error handling: how to diagnose and resolve API errors.
Investigate overview: review customer session results and submitted data in the GBG GO dashboard.

Get Started

Platform