Skip to main content

Persistent ID

info

You don't need to understand this concept to use the API reliably.

The main takeaway: The persistent_id is safe to store, cache, and use as a stable reference to a real-world legal entity.

In G-BRIS, legal entities are constructed by merging data from multiple registries and sources. This merging is performed using deterministic rules based on identifiers (e.g., LEIs or registry numbers). However, on rare occasions, the composition of these merged entities may change, due to improvements in our resolution logic improves or corrections in source data.

This raises an important question:
How can API clients reliably refer to a real-world legal entity over time if its underlying composition may shift?

Why Not Use Registry Numbers?​

While registry numbers are useful, they are not always reliable:

  • In some jurisdictions, a registry number alone is not unique unless paired with a local court or registration authority.
  • In rare cases, a registry number may be absent from G-BRIS data altogether.
  • More critically, if two records with registry numbers A and B are later merged or unmerged, those references may become ambiguous.

Why Not Use Internal IDs?​

Assigning a new ID to each merged entity seem like a solution, but:

  • If two entities are later unmerged, it becomes unclear which resulting entity the original ID should point to.
  • This would introduce instability in systems relying on stored references.

The Solution: persistent_id​

To address this, G-BRIS introduces the persistent_id field.

A persistent_id is designed to remain stable and reliably refer to the same real-world legal entity, even in the rare case that merges or unmerges occur.

How it works:​

  • Each entity in G-BRIS is backed by a set of source documents.
  • Among these, the most trusted source is selected (see: Entity Resolution & Merging).
  • The ID of that document is used as the persistent_id.

This means:

  • If an entity is ever split into two, one of the resulting entities will keep the dissolved merged entity's persistent_id, while the other will obtain a new persistent_id.
  • If multiple documents are merged into one, the highest-trust document determines the resulting persistent_id.

The persistent_id is safe to store, cache, and reference externally.