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

# API-first integration quickstart

> Integrate with GBG GO APIs to start journeys, fetch interactions, and submit verification data

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](/docs/go-v2/platform/account-management/manage-api-clients).
* A tool capable of making HTTP requests, for example, curl or Postman.

<Note>
  API client credentials are different from your GBG GO platform login. They are specifically for programmatic access.
</Note>

## 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](/docs/go-v2/get-started/quickstart/quickstartbusiness#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:

```bash cURL theme={null}
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 JSON theme={null}
{
  "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.

<Warning>
  Store the `access_token` securely. Don't share it in emails, chat messages, client-side code, or publicly accessible locations.
</Warning>

## 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:

```bash cURL theme={null}
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": {}
    }
  }'
```

<Note>
  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.
</Note>

### 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:

```bash cURL theme={null}
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 JSON theme={null}
{
  "instanceId": "Pq_hhIX6-sHUy9FLSDzPLu",
  "status": "started",
  "message": "Journey Pq_hhIX6-sHUy9FLSDzPLu started successfully"
}
```

<Warning>
  Save the `instanceId` — you need it for all subsequent API calls in this journey.
</Warning>

<Tip>
  Replace `@latest` with your specific journey version for production integrations. Using `@latest` can introduce a small delay in processing.
</Tip>

## Step 4: Fetch the interaction

Poll [`/journey/interaction/fetch`](/docs/go-v2/api-reference/endpoint/fetch-interaction) to retrieve the current interaction and discover what data the end user must provide:

```bash cURL theme={null}
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](/docs/go-v2/get-started/key-concepts#domain-elements) that need to be collected:

```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"
  ]
}
```

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](/docs/go-v2/developer-integration/execute-customer-journeys/retrieve-tasks-step#understanding-the-response).

<Accordion title="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](/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` 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.                                                                                            |
</Accordion>

<Note>
  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`.
</Note>

<Note>
  If no `interactionId` is returned yet, the platform is still processing. Keep polling until an `interactionId` appears or `journey.status` changes from `InProgress`.
</Note>

## Step 5: Submit interaction data

Once you've collected data from the end user, submit it using the `interactionId` from the fetch response:

```bash cURL theme={null}
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 JSON theme={null}
{
  "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.

<Tip>
  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.
</Tip>

## Step 6: Fetch journey state

Once all interactions are submitted, poll [`/journey/state/fetch`](/docs/go-v2/api-reference/endpoint/fetch-journey-state) to detect completion and retrieve verification results:

```bash cURL theme={null}
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 JSON expandable theme={null}
{
  "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](/docs/go-v2/developer-integration/execute-customer-journeys/overview): detailed step-by-step reference for each API call.
* [API reference](/docs/go-v2/api-reference/overview): complete request and response definitions.
* [Error handling](/docs/go-v2/developer-integration/error-handling): how to diagnose and resolve API errors.
* [Investigate overview](/docs/go-v2/platform/investigate/overview): review customer session results and submitted data in the GBG GO dashboard.