Entities
Anchors on an identification
Device and visitor identifiers are not proof of a person’s identity. Shared devices and networks can link legitimate users. A missing or all-zero Device ID is not a usable device identity.
How a check ties them together
An identification records the user, visitor, device and IP addresses present in that check. Repeated checks build the account’s device and network history. A shared IP alone does not establish that two accounts belong to one person. Each accepted identification consumes one check from the plan’s included volume. Repeated regular calls for the same user and browser within five minutes create no new check while site pages remain open. Force checks bypass that pause. A browser call starts a check; the completed Risk Score arrives later inidentification.scored. See Identification.
Anonymous checks do not create a signed-in account. Pass the same pseudonymous User HID on each authenticated check to link that account’s activity. Do not assume earlier anonymous checks are retroactively assigned to an account.
The risk of a user, device, visitor or IP
The analytics dashboard shows an identity’s current risk category separately from the Risk Score of one identification. Changing the selected period changes the activity in view; it does not turn the category into the worst score in that period. ShieldLabs considers all available identifications linked to that key within the last 90 days, rather than only the selected reporting period. It calculates the share scoring 60 or more separately from the share scoring 30–59. A check’s effect depends on the total history size.What Trusted, Suspicious and Dangerous mean
The same three labels apply to all four current risk categories. Each label summarizes the history linked to that specific visitor, user, device or public IP:
The score ranges 0–29, 30–59 and 60–100 classify individual identifications. An identity’s current category considers the proportion of checks in those bands, rather than applying a range to its latest check. It is not a percentage probability of fraud. An IP’s category describes activity associated with that address, not every person using the network.
Read Current risk as of and any coverage warning on the card; unavailable evidence is not a Trusted verdict. High-Risk Events are shown separately, with Medium or High confidence.
The
anonymous value has no authenticated account risk category. See Current risk category for its fields and scope, Device ID for matching across browser environments, and Local IP for the two network checks.
For example, a new identification can be Trusted while the linked user is Dangerous because of the account’s other identifications. The visitor, device and IP can each have a different category because each has its own identification history.
In webhooks and History
Anidentification.scored webhook returns the check’s numeric data.risk_score, without the four current identity categories. A History identification card returns risk.score and risk.band for that check when risk.state is ok. Its identity_risk object can also include the linked visitor, user, device and IP categories.
On a History user, visitor, device or IP card, risk.band is that identity’s current category when risk.state is ok; risk.as_of gives its calculation time. An unavailable category is not Trusted. See History card. Read the webhook account-event results separately: their medium and high levels describe event confidence.
A maximum over a page of History results is your own summary of those rows. It does not reproduce the analytics dashboard’s current category or its High-Risk Event state.
The User HID is your account key
Use a stable pseudonymous token generated by your backend. Avoid raw emails, usernames and other personal account data. The snippet sends this value to ShieldLabs, which returns it in results. See Identify signed-in users for the integration. User HID associates activity with an account; it does not authenticate the person making a request to your application.Read them in code
The History API reads identifications and users as lists, and one visitor, device, or IP as a single record. A Private API Key scopes a read to its domain. Start withGET /api/v1/domains and pass the returned id.
next_page_token. History returns stored identifications; it is not a replay feed for multi-account group changes.