Identification

Every visit resolves to six identifiers, and the most durable of them, the DeviceID, holds even after a visitor clears cookies or opens an incognito window. You read the identity and its signals from the webhook or the History API.

The identifier model

Every identify call returns six identifiers. They are ordered here by how durable and useful each one is, from the persistent DeviceID down to the per-call RequestID.

Identifier	How it is made	Persistence
DeviceID	Server-derived; not stored in the browser.	Durable. Survives cleared cookies, incognito, and IP rotation. Browser-bound.
UserHID	Your own hashed account id, passed into the snippet. You set this value yourself.	Whatever you set.
VisitorID	Server-derived from the DeviceID combined with the CookieID.	Resets when cookies are cleared. Many VisitorIDs can map to one DeviceID.
CookieID	A first-party UUID minted in the browser and stored in cookies and site storage.	Lost when cookies or site storage are cleared.
SessionID	A client UUID for the current visit, kept in session storage and short-lived.	Resets after a short window of inactivity, or in a new browser session.
RequestID	A client-generated UUID, one per identify call. It joins the snapshot, the webhook, and the History API together.	Unique per call.

RequestID, SessionID, and CookieID are minted in the browser. DeviceID and VisitorID are computed on the server, so the browser never sees them. You correlate everything by RequestID.

Identifier hierarchy

The six identifiers nest from a single request up to a known account:

RequestID is one identify call.
SessionID is one visit.
CookieID is the browser’s first-party storage.
VisitorID is the DeviceID and CookieID together, the cookie-scoped identity.
DeviceID is the durable, browser-bound device identity.
UserHID is the signed-in account you pass in.

A single DeviceID can sit behind many VisitorIDs, many sessions, and many requests over time.

Why DeviceID is durable

DeviceID is the identifier most analytics tools cannot match. It is server-derived and not stored in the browser. Because nothing about it lives in the cookie, it holds when cookie-based tracking breaks:

Survives cleared cookies. Clearing cookies removes the CookieID, not the identity.
Survives incognito. A private window still maps to the same DeviceID.
Survives IP rotation. Switching networks or using a VPN does not change the identity.

This durability is why a returning person keeps the same DeviceID, even after their cookies expire. See identification accuracy.

DeviceID is browser-bound. The same person on Chrome and on Firefox produces two different DeviceIDs.

When the snippet is blocked or JavaScript is disabled, the DeviceID comes back as the all-zero UUID 00000000-0000-0000-0000-000000000000. A JavaScript-disabled visit scores 90. Route a null or all-zero DeviceID to review rather than auto-allowing it: you cannot recognize a returning person from an identity that was never built.

Why VisitorID resets

VisitorID is built from two inputs: the DeviceID and the CookieID. The DeviceID half is durable. The CookieID half is not. So when a visitor clears cookies:

The CookieID is gone, and the browser mints a fresh one on the next visit.
The server combines the same DeviceID with the new CookieID.
The result is a new VisitorID.

That is by design. One durable DeviceID can sit behind many VisitorIDs over time. Use DeviceID for the most stable handle on a returning person within a browser. Use VisitorID for the cookie-scoped view, and UserHID once a person signs in.

A burst of new VisitorIDs all mapping to one DeviceID, or one VisitorID seen across many DeviceIDs, is itself a signal. The dashboard surfaces these as Patterns.

UserHID is your hashed account id

UserHID is the only identifier you control. It is your own account id, passed into the snippet so ShieldLabs can tie anonymous activity to a known account. Pass a hashed or pseudonymous value, and apply the same transform every time so the same account always maps to the same UserHID.

// Hash the account id before passing it to the snippet.
const userHID = await sha256(currentUser.id); // never the raw id or email
const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
mod.checkAuthenticatedUser(userHID);

Never pass a raw email, username, or primary-key user id as the UserHID. ShieldLabs echoes the UserHID back in webhooks and History, so a raw value would put plaintext account data in those payloads. Always hash it or use a pseudonymous token.

When no one is signed in, call checkAnonymous() and the UserHID is left unset. The snippet setup documents the full method list.

Device Intelligence is part of identification

The output of identification is not just an ID. It is the identity plus the signals around that device, delivered together in one response.

You get	What it is
DeviceID	The persistent, browser-bound identity described above.
Device attributes	The visitor’s `browser`, `os`, and `device_type` (`desktop`, `mobile`, or `tablet`).
Location	`country`, derived from the IP (geolocation), alongside the public IP and, when available, the local IP.
Risk Score (0-100)	An explainable score with a `signals` array naming every signal that fired, detailed under Risk Scoring.
Signals	The anonymity and mismatch signals behind the score, cataloged under Anonymity Signals.

You never call a separate “fingerprint” endpoint and a separate “risk” endpoint. One snippet collects the signals, the server scores them, and the result arrives by webhook (or you read it from the History API).

Example response

A realistic webhook body. The six identifiers arrive alongside the Risk Score and the signals that explain it.

{
  "request_id": "13f84f05-2f3a-4c2e-9b1f-7a6d3e8c1b22",
  "session_id": "a1c9e740-5b6d-4e2a-8f31-0c2b9d4e7f11",
  "cookie_id": "7e2d1b88-3c4f-4a9e-b6d2-1f8a0c5e9d34",
  "device_id": "5eb7fd5c-9a21-4b6e-8c3d-2f1a9e7b0c45",
  "visitor_id": "161dfbad-4e8c-4d1a-9f72-3b6c0a2e8d57",
  "public_ip": {
    "ip": "203.0.113.42",
    "country": "US"
  },
  "os": "Windows",
  "browser": "Chrome",
  "device_type": "desktop",
  "user_hid": "8f14e45fceea167a5a36dedd4bea2543",
  "risk_score": 30,
    "signals": [
    { "name": "proxy", "weight": 10 },
    { "name": "datacenter_ip", "weight": 10 },
    { "name": "abuser", "weight": 10 }
  ],
  "detection_flags": { "proxy": true, "datacenter_ip": true, "abuser": true },
  "observed_at": "2026-06-16T18:00:45Z"
}

Here the score is 30 because three independent network signals each added 10: the IP looks like a proxy, it resolves to a datacenter, and it carries a known-abuser reputation. Webhook signals[].name values are slugs (proxy, datacenter_ip, abuser) — branch on those or on detection_flags. Dashboard / History display labels can change. Read the Risk Score band, the flags, and the action context together — see Acting on the Risk Score. device_id and visitor_id are the server-derived identity. user_hid is your hashed account id, echoed back. The API models reference documents every field and its types.

Next steps

Anonymity Signals

VPN, proxy, Tor, Privacy Relay, and the mismatch signals around each device.

Risk Scoring

The explainable 0 to 100 score and its bands: Clean, Low, Medium, High.

Accuracy

How identification accuracy reaches up to 99%, and where it stops.

Getting started

Features

Frontend

Backend

Billing and usage

Security and privacy

Troubleshooting

Resources

Support

Legal

The identifier model

Identifier hierarchy

Why DeviceID is durable

Why VisitorID resets

UserHID is your hashed account id

Device Intelligence is part of identification

Example response

Next steps

Anonymity Signals

Risk Scoring

Accuracy

​The identifier model

​Identifier hierarchy

​Why DeviceID is durable

​Why VisitorID resets

​UserHID is your hashed account id

​Device Intelligence is part of identification

​Example response

​Next steps

Anonymity Signals

Risk Scoring

Accuracy

The identifier model

Identifier hierarchy

Why DeviceID is durable

Why VisitorID resets

UserHID is your hashed account id

Device Intelligence is part of identification

Example response

Next steps