External Identifiers

External identifiers are a method that allows other systems to store their ID for an object, e.g., a person, in the registry. Since all objects in the registry already have an ID, this might seem counterproductive, but considering that data and data quality are continuously improving in the registry, this provides an opportunity to maintain a consistent link to occasionally changing data.

What can they refer to?

External identifiers are “polymorphic.” This means they can point to different categories of data. In our case, this can be:

Person Asset Type Asset

Example

Let’s say you have a system we call “xyz.” In this system, the person “Ola Normann” has the ID “xyz123.” Ola Normann is also registered in the Registry, with the ID “5574043f-4fc1-48d2-82a6-7dcf73418390.” An entry in “Identifiers” could therefore be:

{
    "source": "xyz",
    "identity": "xyz123",
    "foreign_id": "5574043f-4fc1-48d2-82a6-7dcf73418390",
    "type": "person"
}

Once this is registered, you can query this identity in the registry and retrieve the person and all related data in one query, without needing to track what ID the person has or whether there has been a merge or update of the data.

You can also send a user into Kvipp with that person (or linked asset type / asset) already selected — using the same source and identity in a Kvipp deep link:

https://kvipp.it/identifier/xyz123?source=xyz

Kvipp looks up the identifier in Registry and pre-fills the session. You do not need to put the Registry UUID in the URL if you maintain identifiers instead.

Example 2: Find or create an asset and link an identifier to it

If you have data for the brand, model, and potentially a version number and a serial number, you can send a POST request to the endpoint https://registry.kvipp.io/assets/find with the following example data as JSON:

{
  "serial_number": "MAN000Q0E01000330",
  "brand": "Manitou",
  "model": "280 TJ"
}

If this asset exists, you will receive the object in return. If not, and if you have set the create parameter to true, both the asset type and the asset will be created and returned to you. If it exists, you should check for an external identifier; if not, you can create one with the ID you received from the previous call, e.g.:

{
    "source": "system_x",
    "identity": "ID8812313",
    "foreign_id": "6dd19106-3708-4fea-becc-45ae3c001a4f",
    "type": "asset"
}

Link a DigiQuip QR code to an asset or asset type

On the QR code, there is a seven-character alphanumeric combination (e.g., “PYZEV1Q”). If you want to link this to an asset with ID 22934840-6214-4b84-bfde-7b239c6d2e33, the identifier you should create (if it doesn’t already exist) would be:

{
    "source": "digiquip_qr",
    "identity": "PYZEV1Q",
    "foreign_id": "22934840-6214-4b84-bfde-7b239c6d2e33",
    "type": "asset"
}

Check first if the identifier already exists!

Open Kvipp with an external identifier

External identifiers are the link between your system’s IDs and Registry objects. After you create an identifier in Registry (via API or sync), you can open Kvipp with the linked person, asset type, or asset pre-selected — without embedding Registry UUIDs in your portal or LMS URLs.

{base}/identifier/{identity}?source={source}

Use the exact source and identity from the Registry record. Example for the person above:

https://kvipp.it/identifier/xyz123?source=xyz

Kvipp resolves the identifier, loads the linked object, and redirects to the home screen. If the identifier does not exist, the user sees a not-found page.

When to use identifiers vs Registry UUIDs in Kvipp

Approach	Best when
External identifier deep link	Your integration stores its own IDs; Registry UUIDs may change after merges
Registry UUID deep link	You already have stable Registry id values from API sync

See Kvipp deep links for all entry routes (UUID, brand/model, Kvipp short ID, and combined links).