Subject ID
What a subject id is
Section titled “What a subject id is”Every person or company Gungner knows about has a subject id: an opaque, randomly generated identifier, scoped to your tenant. It carries no structure you can decode — you cannot compute someone’s subject id from their personnummer, an org.nr, or any other identifier. You can only obtain it by looking the subject up.
This is deliberate. A subject id is a pseudonym, not an encoding, so it never leaks the identifier it’s standing in for.
One subject, many reference ids
Section titled “One subject, many reference ids”You’re free to attach your own internal reference ids to a Gungner subject — for example, if the same person appears under two different account numbers in your own system, you can link both of your reference ids to the one Gungner subject. The relationship is many-to-one: many of your reference ids can point at one subject, but a subject always has exactly one canonical identity on Gungner’s side.
Gungner also keeps a history of the identifiers it has used to recognize a subject over time — useful when something upstream changes (a company re-registers, a person’s protection status changes) and you need to understand why a lookup that used to work now behaves differently.
Merges
Section titled “Merges”Occasionally Gungner learns that two subject ids it had been treating separately actually refer to the same real-world person or company. When that happens, Gungner merges them: one subject becomes canonical, and the other becomes a permanent one-hop alias of it. There is no un-merge — if a merge turns out to be wrong, it’s corrected forward with a further merge, never undone.
Every API response, event, and MCP tool result that returns a subject carries both its
canonical id and an aliases array listing every id that now points at it. A subject.merged
event fires whenever a merge happens, so you can react to it if you’re watching the event log.
The practical rule: always read the aliases array on the response you have in front of
you; never assume a subject id you stored earlier is still the canonical one. Treat what the
API tells you right now as the source of truth, not a value you cached.
Why it matters
Section titled “Why it matters”If you’re feeding Gungner’s identity, KYB, or KYC data into a downstream system — a risk engine, a case-management tool, a transaction-monitoring product — the subject id is the join key that lets that system line up Gungner’s data with its own records for the same person or company. Get the merge and alias behavior right, and that join stays correct even as subjects get consolidated over time.
- Canonical objects and evidence — what a subject actually looks like on the wire, and how every field is backed by evidence.
- Events and webhooks — how to hear about a
subject.mergedevent as it happens.