Skip to main content
When starting a journey, you can pass reference numbers for internal tracking purposes. This allows you to link verification sessions in GBG GO with records in your own systems. GBG GO uses the context.subject.sessions[0] object to handle reference numbers. You can provide numbers that best fit your use case and you’re not limited to just one. Pass as many reference numbers as you need to track sessions across multiple systems or databases. These numbers are passed through the GO API unchanged and returned in the /journey/state/fetch API responses, allowing you to correlate verification results with your internal records.

​
Use cases for reference numbers

Common use cases for passing reference numbers include:
  • Provide CRM IDs for end users to find all associated verification journeys.
  • Link verification sessions to customer records in your database.
  • Maintain consistent identifiers for compliance and reporting.
GO does not process or validate these identifiers. They exist solely for your internal tracking purposes.

​
Sessions object structure

The ‘sessions’ field is designed to store one or more objects containing unique tracking identifiers and related details for each user session. Use it to record contextually relevant information specific to a session.
LocationData typeDescription
context.subject.sessions[0]Array of objectsContains session-specific reference numbers and metadata, for example, context.subject.sessions[0].user.id

​
Available fields within each session object

You can include any combination of the following fields based on your tracking requirements:
Field categoryDetails
useruser.id
user.email
user.domain
clientclient.id
client.ip
client.address
devicedevice.id
device.manufacturer
device.model.identifier
device.model.name
tracetrace.id
spanspan.id
transactiontransaction.id
Example POST request to the /journey/start endpoint with multiple reference fields:
JSON
{
  "resourceId": "your-journey-resourceId@latest",
  "context": {
    "subject": {
      "sessions": [
        {
          "user": {
            "id": "user-8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
            "email": "[email protected]",
            "domain": "example.com"
          },
          "client": {
            "id": "client-3f4e5d6c-7b8a-9c0d-1e2f-3a4b5c6d7e8f",
            "ip": "198.51.100.42",
            "address": "456 Business Ave, Floor 3, San Francisco, CA 94105, USA"
          },
          "device": {
            "id": "device-9d8c7b6a-5e4f-3d2c-1b0a-9e8d7c6b5a4f",
            "manufacturer": "Apple",
            "model": {
              "identifier": "iPhone14,3",
              "name": "iPhone 13 Pro Max"
            }
          },
          "trace": {
            "id": "trace-f1e2d3c4b5a6978869708f5e4d3c2b1a"
          },
          "span": {
            "id": "span-6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
          },
          "transaction": {
            "id": "txn-4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a"
          }
        }
      ]
    }
  }
}
You don’t need to include all available fields. Choose the ones that are relevant to your tracking needs.

​
Retrieve reference numbers from API responses

All reference numbers you provide are returned in the Fetch journey state /journey/state/fetch response within the data.context.subject object. Example response from the /journey/state/fetch endpoint:
JSON
{
  "metaData": {
    "createdTime": "2025-12-12T09:53:51.962Z",
    "completedTime": "2025-12-12T09:53:54.431Z"
  },
  "status": "Completed",
  "data": {
    "context": {
      "process": {
        "flow": {
          "peps_and_sanctions_uk": {
            "process": {
              "journey": {
                "name": "Customer Verification Journey",
                "id": "your-journey-id",
                "version": "v1",
                "startedAt": "2025-12-12T09:53:51.976Z"
              },
              "instance": {
                "id": "PiJ2zqwT10AR8K26Bs5UnWSg",
                "instanceId": "PRC-76ceac13-d740-11f0-adba-06ce549d64a0"
              }
            },
            "result": {
              "advice": {
                "decision": "no_hit",
                "sanctions_hit": "Not Available",
                "pep_hit": "Not Available",
                "adverse_media_hit": "Not Available",
                "customDecision": null
              },
              "note": {},
              "status": "complete",
              "outcome": "NO MATCH"
            }
          }
        },
        "journey": {
          "name": "Customer Verification Journey",
          "id": "your-journey-id",
          "version": "v1",
          "startedAt": "2025-12-12T09:53:51.976Z",
          "endedAt": "2025-12-12T09:53:54.350Z",
          "durationMilliSec": 2374
        },
        "instance": {
          "id": "PiJ2zqwT10AR8K26Bs5UnWSg",
          "instanceId": "PRC-76ceac13-d740-11f0-adba-06ce549d64a0"
        }
      },
      "subject": {
        "identity": {
          "firstName": "Jane",
          "lastNames": ["Smith"],
          "dateOfBirth": "1987-04-19",
          "currentAddress": {
            "locality": "London",
            "country": "GBR"
          }
        },
        "sessions": [
          {
            "user": {
              "id": "user-8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
              "email": "[email protected]",
              "domain": "example.com"
            },
            "client": {
              "id": "client-3f4e5d6c-7b8a-9c0d-1e2f-3a4b5c6d7e8f",
              "ip": "198.51.100.42",
              "address": "456 Business Ave, Floor 3, San Francisco, CA 94105, USA"
            },
            "device": {
              "id": "device-9d8c7b6a-5e4f-3d2c-1b0a-9e8d7c6b5a4f",
              "manufacturer": "Apple",
              "model": {
                "identifier": "iPhone14,3",
                "name": "iPhone 13 Pro Max"
              }
            },
            "trace": {
              "id": "trace-f1e2d3c4b5a6978869708f5e4d3c2b1a"
            },
            "span": {
              "id": "span-6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
            },
            "transaction": {
              "id": "txn-4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a"
            }
          }
        ]
      },
      "result": {
        "status": "complete",
        "error": []
      }
    }
  },
  "instanceId": "PiJ2zqwT10AR8K26Bs5UnWSg"
}
The data is preserved exactly as submitted and returned in the data.context.subject structure. The response also includes journey processing details and results from executed modules.
The example response above shows results from a PEPs and sanctions screening module, but the structure applies to all journey types regardless of which modules are configured.