> ## 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
> Get started with the GBG GO Platform API. Learn how to start an identity verification journey, retrieve assigned tasks, submit identity data, and receive structured verification results.
## Overview
This quickstart guides you through the following:
* Create a journey with the PEPs and Sanctions module.
* Set up authentication.
* Execute your first customer journey.
* Retrieve tasks, submit data, and confirm the journey completes.
This guide walks you through integrating customer verification workflows into a frontend application using the GBG GO API.
## Prerequisites
Before running this quickstart, complete the following:
* You have created an API client in the Account management portal. Your API client provides the credentials required to authenticate your API requests:
* `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-v1/platform/account-management/manage-api-clients).
API client credentials are different from your personal GBG GO platform login. API client credentials are specifically for programmatic access and should not be confused with the username and password you use to log into the GBG GO dashboard.
* You have a development environment capable of making HTTP requests, for example, Postman.
## Step 1: Create a journey with the PEPs and Sanctions module
Before you can execute a journey using the API, you need to create one in the GBG GO platform. In this quickstart, you'll use the **PEPs and Sanctions** module, which screens individuals against global watchlists for Politically Exposed Persons (PEPs) and sanctioned entities. This helps your organisation meet Anti-Money Laundering (AML) and Counter-Terrorism Financing (CTF) obligations.
When a customer's data is submitted, the module compares it against international databases and returns a result, either a hit (match found), no hit (no match), or not available.
To create the journey:
1. Log in to the GBG GO platform and create a new journey in the journey builder.
2. Click **Browse and add modules**.
3. Search for **PEPs and Sanctions** or navigate to the *Compliance Screening* category.
4. Select the **PEPs and Sanctions** module and choose the **UK Instance (with Adverse Media and OGM) variant**.
5. Click **Add to journey**.
6. Click **Configure outcomes** and set up rules for match and no-match results. For example, set the outcome to "Match" when *PEPs and Sanctions Results* is *PEPs and Sanctions Hit*.
7. **Publish** the journey to *Preview*.
8. Note the journey's **resource ID** and **version** from the journey dashboard. You'll need these for the API calls. See [Publish a journey](/docs/go-v1/platform/journey-builder/publish-journey) for details on how to find these values.
For a detailed guide on configuring the PEPs and Sanctions module, including variant options and outcome rules, see [Understanding the PEPs and Sanctions module](/docs/go-v1/guides/product-guides/peps-and-sanctions).
## Step 2: Request an access token for authentication
Make a POST request to obtain 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'
```
You'll receive an access token that you'll use for all subsequent API calls, like this:
```json JSON theme={null}
{
"access_token": "your-access-token",
"token_type": "Bearer",
"expires_in": 3600
}
```
Store the `access_token` value securely. Do not share them in emails, chat messages, client-side code or publicly accessible sites.
If you run into a credentials error when making a token cURL request, then your client ID or client secret probably aren't correct. Check the values in the Account management portal, or regenerate the client secret if needed. See [Manage API clients](/docs/go-v1/platform/account-management/manage-api-clients).
## Step 3: Start your first customer journey
Use your access token and the journey resource ID from Step 1 to start a journey. Make a POST request to the [`(/journey/start)`](/docs/go-v1/api-reference/endpoint/start-journey) endpoint:
```bash cURL theme={null}
curl --request POST \
--url https://eu.platform.go.gbgplc.com/captain/api/journey/start \
--header 'Authorization: Bearer your_access_token' \
--header 'Content-Type: application/json' \
--data '{
"resourceId": "your-journey-resourceID@version",
"context": {
"subject": {
"identity": {
"firstName": "John",
"middleNames": ["Michael"],
"lastNames": ["Doe"],
"dateOfBirth": "1961-06-01"
},
"documents": [],
"biometrics": []
}
}
}'
```
You are checking the name John Michael Doe, born on June 1, 1961, against the PEPs and Sanctions databases.
You'll receive an `instanceId` that represents your active journey:
```json JSON theme={null}
{
"instanceId": "QxLNUpNEPiFR9LurKp8BmJn3"
}
```
Save this `instanceId` — you'll need it for every subsequent step.
Replace `your-journey-resourceID@version` with the resource ID and version from Step 1. For example: `"resourceId": "092a0947e99aa3e955344178a3d010413769e0acca6d97728dd758e04b449566@7upcgqlz"`.
## Step 4: Retrieve task IDs
After starting a journey, GBG GO assigns tasks based on the modules in your journey. Retrieve the task IDs to find out what needs to be completed.
Send a POST request to the [`/journey/task/list`](/docs/go-v1/api-reference/endpoint/retrieve-tasks) endpoint using the `instanceId` from Step 3:
```bash cURL theme={null}
curl --request POST \
--url https://eu.platform.go.gbgplc.com/captain/api/journey/task/list \
--header 'Authorization: Bearer your_access_token' \
--header 'Content-Type: application/json' \
--data '{
"instanceId": "your-instance-id"
}'
```
You'll receive a list of tasks assigned to the journey:
```json JSON theme={null}
{
"status": "InProgress",
"instanceId": "QxLNUpNEPiFR9LurKp8BmJn3",
"tasks": [
{
"taskId": "TkoviRO58Q8R7qPnAkLAqBAT",
"variantId": "age_verification_all_ssn_dob_required"
}
]
}
```
Note the `taskId`. You'll use it in the next step to retrieve the task's schema and to submit data.
## Step 5: Retrieve tasks with their schema
Now fetch the tasks along with their corresponding JSON schema using the `taskId`. This tells you the exact fields you need to submit for each task, in a single API call.
Send a POST request to the [`/journey/task/list/schema`](/docs/go-v1/api-reference/endpoint/retrieve-tasks-with-their-schema) endpoint:
```bash cURL theme={null}
curl --request POST \
--url https://eu.platform.go.gbgplc.com/captain/api/journey/task/list/schema \
--header 'Authorization: Bearer your_access_token' \
--header 'Content-Type: application/json' \
--data '{
"instanceId": "your-instance-id"
}'
```
You receive the tasks with a `schema` reference and the full schema definitions:
```json JSON expandable theme={null}
{
"status": "InProgress",
"instanceId": "QxLNUpNEPiFR9LurKp8BmJn3",
"tasks": [
{
"taskId": "TkoviRO58Q8R7qPnAkLAqBAT",
"variantId": "age_verification_all_ssn_dob_required",
"schema": {
"$ref": "#/schemas/dkBf7i_SNMGcfh3CK7z0W7326V2EYPfJ"
}
}
],
"schemas": {
"dkBf7i_SNMGcfh3CK7z0W7326V2EYPfJ": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"context": {
"type": "object",
"properties": {
"subject": {
"type": "object",
"properties": {
"identity": {
"type": "object",
"properties": {
"firstName": { "type": "string" },
"lastNames": { "type": "array", "items": { "type": "string" } },
"dateOfBirth": { "type": "string" },
"currentAddress": {
"type": "object",
"properties": {
"locality": { "type": "string" },
"postalCode": { "type": "string" },
"country": { "type": "string" }
}
}
},
"required": ["firstName", "lastNames"]
}
},
"required": ["identity"]
}
},
"required": ["subject"]
}
},
"required": ["context"]
}
}
}
```
If you didn't have the name John Michael Doe and date of birth June 1, 1961 in the initial context when starting the journey, the task schema would indicate that these fields are required for the task to be completed. Use this schema to understand what data you need to collect from the user to complete the task. In this case, you would need to collect the user's first name, last name, and date of birth, to complete the task. Use this information to build out your frontend and collect the required data from the user.
Each task's `schema.$ref` points to a key in the `schemas` map. The schema defines the full `context` structure you need to submit, including required fields and data types. Use this to build your submission payload in the next step.
For more details on reading and using task schemas, see [Manage schemas](/docs/go-v1/developer-integration/execute-customer-journeys/manage-schemas-step) and the [User data schema](/docs/go-v1/api-reference/schema) reference.
## Step 6: Submit task data
Use the `taskId` from [Step 4](#step-4-retrieve-task-ids) and the schema from [Step 5](#step-5-retrieve-tasks-with-their-schema) to submit the required customer data. Send a POST request to the [`/journey/task/update`](/docs/go-v1/api-reference/endpoint/submit-task-data) endpoint:
```bash cURL theme={null}
curl --request POST \
--url https://eu.platform.go.gbgplc.com/captain/api/journey/task/update \
--header 'Authorization: Bearer your_access_token' \
--header 'Content-Type: application/json' \
--data '{
"intent": "Complete",
"instanceId": "your-instance-id",
"taskId": "your-task-id",
"context": {
"subject": {
"identity": {
"firstName": "John",
"middleNames": ["Michael"],
"lastNames": ["Doe"],
"dateOfBirth": "1961-06-01"
}
}
}
}'
```
The `"intent": "Complete"` field is required to mark the task as finished. The fields in `context` depend on your journey's task schema. Use the [Manage schemas](/docs/go-v1/developer-integration/execute-customer-journeys/manage-schemas-step) guide and [User data schema](/docs/go-v1/api-reference/schema) reference to see the exact structure for your journey.
If the journey has more tasks, then repeat [Step 4](#step-4-retrieve-task-ids) to [Step 6](#step-6-submit-task-data) until no tasks remain.
## Step 7: Fetch journey state
After submitting all task data, check whether the journey has completed. Send a POST request to the [`/journey/state/fetch`](/docs/go-v1/api-reference/endpoint/fetch-journey-state) endpoint:
```bash cURL theme={null}
curl --request POST \
--url https://eu.platform.go.gbgplc.com/captain/api/journey/state/fetch \
--header 'Authorization: Bearer your_access_token' \
--header 'Content-Type: application/json' \
--data '{
"instanceId": "your-instance-id"
}'
```
When the journey completes, you'll receive a response like this:
```json JSON expandable theme={null}
{
"metaData": {
"createdTime": "2025-10-15T15:17:07.553Z",
"completedTime": "2025-10-15T15:17:23.619Z"
},
"status": "Completed",
"data": {
"context": {
"process": {
"flow": {
"peps_and_sanctions_adverseMedia_ogm": {
"process": {
"journey": {
"name": "PEPS",
"id": "20848067f46658d02c0ce53501dcd72a25a6ecc0577b1f9259b6bd0a7fd8371a",
"version": "5e8puio8",
"startedAt": "2025-10-15T15:17:07.568Z"
},
"instance": {
"id": "PiIDhX14qdoR8J6y6vybL8Xk",
"instanceId": "PRC-03857d78-a9da-11f0-9eb2-eafc9b2fc5e4"
}
},
"subject": {
"identity": {
"firstName": "John",
"middleNames": [
"Michael"
],
"lastNames": [
"Doe"
],
"dateOfBirth": "1985-03-15"
},
"uid": null
},
"result": {
"advice": {
"decision": "hit",
"sanctions_hit": "Full name and DOB matched",
"pep_hit": "Not Available",
"adverse_media_hit": "Match found for name",
"sent_to_ogm": true,
"sanction_candidate_score": 100,
"customDecision": null
},
"note": {
"pep_match_details": {
"fullname": "John Michael Doe",
"aliases": [
"John M. Doe",
"J. Michael Doe",
"Johnny Doe"
],
"addresses": [
{
"lines": [""],
"locality": "Chicago",
"country": "",
"superAdministrativeArea": "Illinois"
}
],
"dates": [
{
"type": "Birth",
"date": "1985-03-15"
}
]
},
"sanctions_match_details": [
{
"fullName": "John Michael Doe",
"bodies": [
"Monaco Minister of State",
"United Kingdom Foreign, Commonwealth & Development Office",
"French Ministry of Economy and Finance, DG Treasury",
"European Union Council (EU)",
"Office of Foreign Assets Control (OFAC)",
"Swiss State Secretariat for Economic Affairs",
"United States Department of State",
"New Zealand Ministry of Foreign Affairs & Trade",
"Australian Department of Foreign Affairs and Trade",
"Ukraine National Security and Defence Council",
"Canadian Government Sanctions",
"Her Majesty's Treasury/Office of Financial Sanction Implementation (HMT/OFSI)",
"Japan Ministry of Finance"
],
"aliases": [
"John M. Doe",
"J. Michael Doe",
"John Doe",
"Johnny Doe",
"J.M. Doe",
"Jonathan Michael Doe",
"Jon Michael Doe",
"Johnathan Doe"
],
"addresses": [
{
"lines": [
""
],
"locality": "Chicago",
"country": "",
"superAdministrativeArea": ""
}
],
"dates": [
{
"type": "Birth",
"date": "1985-03-15"
},
{
"type": "Death",
"date": "2024-11-20"
}
]
}
],
"adverse_media_match_details": {
"sanctionsType": "NM",
"subjectName": "John Michael Doe",
"inputName": "John Michael Doe",
"processedDate": "2025-10-15 16:17:13",
"details": [
{
"sourceID": "9349",
"subjectMatched": "John Michael Doe",
"text": "Dec 19, 2020, 3:25 AM The 20 biggest financial fraud cases of 2020 2020 was another roller coaster year in finance, and for no one more than financial executive John Michael Doe and some of his closest business partners",
"score": "97",
"category": "ALLNM",
"url": "https://www.businessinsider.com.au/the-biggest-fraud-cases-of-2020-investigation-2020-12",
"textHeading": "Dec 19, 2020, 3:25 AM The 20 biggest financial fraud cases of 2020 2020 was another roller coaster",
"newsOutlet": "businessinsider.com"
},
{
"sourceID": "11226",
"subjectMatched": "John Michael Doe",
"text": "THE US has slapped new sanctions on executives in retaliation to their alleged roles in the 2019 financial schemes. The sanctions include target John Michael Doe, who has been tied ",
"score": "97",
"category": "ALLNM",
"url": "https://www.thesun.ie/news/2313583/us-slaps-fresh-sanctions-on-top-executives-including-financial-mastermind/",
"textHeading": "THE US has slapped new sanctions on executives in retaliation to their alleged roles in the 2019 fi",
"newsOutlet": "thesun.ie"
}
],
"pageNumber": 1,
"totalItems": 100,
"totalPages": 5
}
},
"status": "complete",
"outcome": "MATCH"
}
}
},
"journey": {
"name": "PEPS",
"id": "20848067f46658d02c0ce53501dcd72a25a6ecc0577b1f9259b6bd0a7fd8371a",
"version": "5e8puio8",
"startedAt": "2025-10-15T15:17:07.568Z",
"endedAt": "2025-10-15T15:17:23.497Z",
"durationMilliSec": 15929
},
"instance": {
"id": "PiIDhX14qdoR8J6y6vybL8Xk",
"instanceId": "PRC-03857d78-a9da-11f0-9eb2-eafc9b2fc5e4"
}
},
"subject": {
"identity": {
"firstName": "John",
"middleNames": [
"Michael"
],
"lastNames": [
"Doe"
],
"dateOfBirth": "1985-03-15"
}
},
"result": {
"status": "complete",
"error": []
}
}
},
"instanceId": "PiIDhX14qdoR8J6y6vybL8Xk"
}
```
The journey state response contains the full state and result of the journey. The exact `result` payload differs by module, but the top-level structure is consistent across journeys.
#### Top-level fields
| Field | Type | Description |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------------ |
| `instanceId` | string | Unique identifier for the journey instance. Use this to reference the journey in subsequent API calls. |
| `status` | string | Overall journey status. One of `InProgress`, `Completed`, or `Failed`. |
| `metaData.createdTime` | string | ISO 8601 timestamp for when the journey was started. |
| `metaData.completedTime` | string | ISO 8601 timestamp for when the journey reached a terminal state. |
#### Subject and process
| Field | Type | Description |
| ------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.context.subject.identity` | object | The subject's identity data submitted during the journey, including `firstName`, `middleNames`, `lastNames`, and `dateOfBirth`. |
| `data.context.process.journey` | object | Metadata about the journey definition: `name`, `id`, `version`, `startedAt`, `endedAt`, and `durationMilliSec`. |
| `data.context.process.instance` | object | The journey instance identifiers (`id` and `instanceId`). |
| `data.context.process.flow` | object | A map keyed by module name (for example, `peps_and_sanctions_adverseMedia_ogm`). Each entry contains the module's `process`, `subject`, and `result` data. |
| `data.context.result.status` | string | Overall journey result status. |
| `data.context.result.error` | array | Errors encountered during execution. Empty when the journey completed without errors. |
#### Module result (`flow..result`)
| Field | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `advice` | object | The module's verification decision and supporting fields. Shape is module-specific. |
| `note` | object | Detailed match data returned by the module. Use this for investigation or audit display. |
| `status` | string | Module-level status, for example, `complete`. |
| `outcome` | string | Final outcome derived from the outcome rules configured in the journey builder, for example, `MATCH` or `NO_MATCH`. |
#### PEPs and Sanctions advice
| Field | Type | Description |
| -------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `decision` | string | The module's overall decision, for example, `hit` or `no_hit`. |
| `sanctions_hit` | string | Description of the sanctions match, for example, `Full name and DOB matched`. `Not Available` indicates no match. |
| `pep_hit` | string | Description of the PEP (Politically Exposed Person) match, or `Not Available` if no match. |
| `adverse_media_hit` | string | Description of the adverse media match, or `Not Available` if no match. |
| `sent_to_ogm` | boolean | Whether the case was sent to Ongoing Monitoring (OGM) for continuous screening. |
| `sanction_candidate_score` | number | Match confidence score for the sanctions candidate (0–100). Higher values indicate stronger matches. |
| `customDecision` | string \| null | Custom decision value if configured in the journey, otherwise `null`. |
#### PEP and sanctions match details (`note.pep_match_details`, `note.sanctions_match_details[]`)
| Field | Type | Description |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fullname` / `fullName` | string | The matched person's full name as held in the watchlist. |
| `aliases` | array of string | Alternative names the subject is known by, including nicknames, initials, and alternate spellings. |
| `bodies` | array of string | Sanctioning bodies or authorities that have listed the subject (sanctions matches only), for example, `Office of Foreign Assets Control (OFAC)`. |
| `addresses` | array of object | Known addresses associated with the matched subject. Each entry contains `lines`, `locality`, `country`, and `superAdministrativeArea`. |
| `dates` | array of object | Significant dates for the matched subject. Each entry has a `type` (for example, `Birth`, `Death`) and an ISO 8601 `date`. |
#### Adverse media match details (`note.adverse_media_match_details`)
| Field | Type | Description |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sanctionsType` | string | Category code of the adverse media match, for example, `NM` (negative media). |
| `subjectName` | string | The matched subject's name as identified in the media source. |
| `inputName` | string | The name submitted to the module for screening. |
| `processedDate` | string | Timestamp when the adverse media check was processed. |
| `details` | array of object | List of matched media articles. Each entry contains `sourceID`, `subjectMatched`, `text`, `score`, `category`, `url`, `textHeading`, and `newsOutlet`. |
| `pageNumber` | number | Current page of paginated media results. |
| `totalItems` | number | Total number of matched media items found. |
| `totalPages` | number | Total number of pages of media results. |
The `advice` and `note` shapes vary per module. For the exact schema returned by each module variant, see [Modules](/docs/go-v1/platform/modules/overview).
The result above shows a completed journey with the final outcome of "MATCH". The `status` field indicates that the journey has completed successfully. The `context` field contains the full data context of the journey, including all information about the subject, process, and results from any modules or steps in the journey.
John's full name and date of birth were successfully verified, resulting in a "hit" for sanctions screening. The module returned a match with a sanctions list and adverse news articles, providing detailed information about the match and related news articles.
When you see `"status": "Completed"`, the journey is done and your integration is working end to end.
| 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. |
If the status is `InProgress`, then go back to [Step 4](#step-4-retrieve-task-ids) to retrieve and complete remaining tasks.
## Next steps
Now that you've completed a full journey execution from start to `Completed`, check out the following guides to learn more:
* [Execute journey overview](/docs/go-v1/developer-integration/execute-customer-journeys/overview) for in-depth guidance on each step.
* [Complete API reference documentation](/docs/go-v1/api-reference/overview).
* [Handle errors](/docs/go-v1/developer-integration/error-handling) for troubleshooting failed journeys.