Quickstart for developers

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 is intended for developers who need to integrate customer verification workflows into their frontend applications.

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