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.

​
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:
  • Your GBG account manager has provided your API credentials. These credentials are required to authenticate your API requests. They include:
    • client_id: Your unique API client identifier.
    • client_secret: Your secret key for API authentication.
    • username: Your API username.
    • password: Your API password.
    • grant_type: Type in password (this is fixed and does not change).
API credentials are different from your personal GBG GO platform login. API credentials are specifically for programmatic access and should not be confused with the username/password you use to log into the GBG GO dashboard.
  • Your password has been reset from the temporary one (required before API authentication). Ask your account manager for help with password reset.
  • 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 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.

​
Step 2: Request an access token for authentication

Make a POST request to obtain your Bearer token:
cURL
curl --request POST \
 --url https://api.auth.gbgplc.com/as/token.oauth2 \
 --header 'accept: application/json' \
 --header 'content-type: application/x-www-form-urlencoded' \
 --data 'client_id=your-client-id&client_secret=your-client-secret&username=your-username&password=your-password&grant_type=password'
You’ll receive an access token that you’ll use for all subsequent API calls, like this:
JSON
{
  "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 credentials probably aren’t correct. Contact your account manager for the correct or updated credentials.

​
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) endpoint:
cURL
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
{
    "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 endpoint using the instanceId from Step 3:
cURL
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
{
  "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 endpoint:
cURL
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
{
  "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 and the User data schema reference.

​
Step 6: Submit task data

Use the taskId from Step 4 and the schema from Step 5 to submit the required customer data. Send a POST request to the /journey/task/update endpoint:
cURL
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 guide and User data schema reference to see the exact structure for your journey.
If the journey has more tasks, then repeat Step 4 to Step 6 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 endpoint:
cURL
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
{
    "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

FieldTypeDescription
instanceIdstringUnique identifier for the journey instance. Use this to reference the journey in subsequent API calls.
statusstringOverall journey status. One of InProgress, Completed, or Failed.
metaData.createdTimestringISO 8601 timestamp for when the journey was started.
metaData.completedTimestringISO 8601 timestamp for when the journey reached a terminal state.

​
Subject and process

FieldTypeDescription
data.context.subject.identityobjectThe subject’s identity data submitted during the journey, including firstName, middleNames, lastNames, and dateOfBirth.
data.context.process.journeyobjectMetadata about the journey definition: name, id, version, startedAt, endedAt, and durationMilliSec.
data.context.process.instanceobjectThe journey instance identifiers (id and instanceId).
data.context.process.flowobjectA 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.statusstringOverall journey result status.
data.context.result.errorarrayErrors encountered during execution. Empty when the journey completed without errors.

​
Module result (flow.<module>.result)

FieldTypeDescription
adviceobjectThe module’s verification decision and supporting fields. Shape is module-specific.
noteobjectDetailed match data returned by the module. Use this for investigation or audit display.
statusstringModule-level status, for example, complete.
outcomestringFinal outcome derived from the outcome rules configured in the journey builder, for example, MATCH or NO_MATCH.

​
PEPs and Sanctions advice

FieldTypeDescription
decisionstringThe module’s overall decision, for example, hit or no_hit.
sanctions_hitstringDescription of the sanctions match, for example, Full name and DOB matched. Not Available indicates no match.
pep_hitstringDescription of the PEP (Politically Exposed Person) match, or Not Available if no match.
adverse_media_hitstringDescription of the adverse media match, or Not Available if no match.
sent_to_ogmbooleanWhether the case was sent to Ongoing Monitoring (OGM) for continuous screening.
sanction_candidate_scorenumberMatch confidence score for the sanctions candidate (0–100). Higher values indicate stronger matches.
customDecisionstring | nullCustom decision value if configured in the journey, otherwise null.

​
PEP and sanctions match details (note.pep_match_details, note.sanctions_match_details[])

FieldTypeDescription
fullname / fullNamestringThe matched person’s full name as held in the watchlist.
aliasesarray of stringAlternative names the subject is known by, including nicknames, initials, and alternate spellings.
bodiesarray of stringSanctioning bodies or authorities that have listed the subject (sanctions matches only), for example, Office of Foreign Assets Control (OFAC).
addressesarray of objectKnown addresses associated with the matched subject. Each entry contains lines, locality, country, and superAdministrativeArea.
datesarray of objectSignificant 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)

FieldTypeDescription
sanctionsTypestringCategory code of the adverse media match, for example, NM (negative media).
subjectNamestringThe matched subject’s name as identified in the media source.
inputNamestringThe name submitted to the module for screening.
processedDatestringTimestamp when the adverse media check was processed.
detailsarray of objectList of matched media articles. Each entry contains sourceID, subjectMatched, text, score, category, url, textHeading, and newsOutlet.
pageNumbernumberCurrent page of paginated media results.
totalItemsnumberTotal number of matched media items found.
totalPagesnumberTotal 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.
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.
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.
If the status is InProgress, then go back to Step 4 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: