API-first integration quickstart

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.

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:

Log in to the GBG GO platform and create a new journey in the journey builder.
Click Browse and add modules.
Search for PEPs and Sanctions or navigate to the Compliance Screening category.
Select the PEPs and Sanctions module and choose the UK Instance (with Adverse Media and OGM) variant.
Click Add to journey.
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.
Publish the journey to Preview.
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 '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

{
  "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.

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

Understand the response schema

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

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 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 for in-depth guidance on each step.
Complete API reference documentation.
Handle errors for troubleshooting failed journeys.

Get Started

Platform

Developer Integration

Digital IDs

Resources

API-first integration quickstart

Overview

Prerequisites

Step 1: Create a journey with the PEPs and Sanctions module

Step 2: Request an access token for authentication

Step 3: Start your first customer journey

Step 4: Retrieve task IDs

Step 5: Retrieve tasks with their schema

Step 6: Submit task data

Step 7: Fetch journey state

Top-level fields

Subject and process

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

PEPs and Sanctions advice

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

Adverse media match details (`note.adverse_media_match_details`)

Next steps

​Overview

​Prerequisites

​Step 1: Create a journey with the PEPs and Sanctions module

​Step 2: Request an access token for authentication

​Step 3: Start your first customer journey

​Step 4: Retrieve task IDs

​Step 5: Retrieve tasks with their schema

​Step 6: Submit task data

​Step 7: Fetch journey state

​Top-level fields

​Subject and process

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

​PEPs and Sanctions advice

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

​Adverse media match details (note.adverse_media_match_details)

​Next steps

Overview

Prerequisites

Step 1: Create a journey with the PEPs and Sanctions module

Step 2: Request an access token for authentication

Step 3: Start your first customer journey

Step 4: Retrieve task IDs

Step 5: Retrieve tasks with their schema

Step 6: Submit task data

Step 7: Fetch journey state

Top-level fields

Subject and process

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

PEPs and Sanctions advice

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

Adverse media match details (`note.adverse_media_match_details`)

Next steps