Entities
Identifications, users and visitors are entities. Devices and IP addresses are anchors on an identification: each has an identifier, but neither is an entity of the same kind. Entities explains how a check connects them. Identifiers explains how each identifier is built.Identification
One check by the snippet on your site. It runs when you callcheckAnonymous, checkAuthenticatedUser or a forceCheck* variant. Each identification has one visitor, one device and one public IP, and no more than one user and one local IP. It returns a Risk Score and named risk signals. Your plan counts identifications. The identification is the check itself. Its fields include the Risk Score, risk band and risk signals; see Data models for the response fields. Checks connect the user, visitor, device and IP addresses observed together. An analytics dashboard card separates current risk from activity in the selected period. See Entity cards.
Identification ID
The identifier of one check. It connects the check to the notification containing its calculated risk and to its History row. You can use it to associate an action in your application with that check. Deduplicate repeated deliveries of the notification byevent_id. Key: identification_id.
User
An account in your application. It is present when the check is made for a signed-in user and absent on an anonymous check. Its identifier is the User HID. High-Risk Events are detected for the user, rather than for a single identification.User HID
Your account, keyed by the hashed or pseudonymous ID you pass tocheckAuthenticatedUser. Do not pass a raw email address or login. Users, account-level risk and all four High-Risk Events are built on this key. Anonymous checks send "anonymous". Webhook and History key: user_hid.
Pseudonymization
Replacing a direct account identifier, such as an email or login, with a stable token before sending it to ShieldLabs. Generate the User HID on your backend and use the same token for the same account across sessions. A server-side HMAC can create this token without exposing the original identifier or its secret to the browser. A plain hash of a guessable email does not make it secret. Pseudonymization preserves the ability to link account activity; it does not make that activity anonymous. See User HID generation.Visitor
A site visitor who can be distinguished from other visitors. The visitor is based on a cookie and a device. Its identifier is the Visitor ID.Visitor ID
The identifier used to recognize this visitor. It may change when the cookie or device changes. Key:visitor_id.
Anchors on an identification
A device, public IP and local IP accompany an identification. They have identifiers, and the analytics dashboard can open a card for a device or public IP. They are not entities in the same sense as an identification, user or visitor.Device ID
Device ID is an identifier ShieldLabs calculates using its own device fingerprinting technology, which analyzes hardware and software characteristics of the browser environment. Activity from the same device remains recognizable after cookies are cleared, in private browsing and after IP changes. In account history, this identifier connects visits that would look new based on their cookie or network address. It helps identify related accounts and repeat activity involving bonuses or trial periods. For High-Risk Events, ShieldLabs also matches devices within the account using its own algorithms. The characteristic sets account for platform differences and help recognize one physical device across browser-environment changes, even whendevice_id values differ. For example, Chrome and Microsoft Edge on one computer have different identifiers. This matching supports device recognition and reduces the risk of incorrectly merging different devices.
The identifier is returned in device_id in both identification.scored and History. An empty or zero value means a usable device identifier could not be obtained.
Public IP
The public address of an identification and its country. Webhook:public_ip (ip, country). History search type: ip.
Local IP
Local IP is an additional network address. ShieldLabs uses two separate network checks: its own WebRTC session on its servers, and a browser network check through a separate server. The result is recorded separately from the Public IP from which the HTTP request reached ShieldLabs. The address exposes the network exit discovered by the browser check. It can differ from the request address, for example when the page uses a VPN or proxy but the browser check sees another path. The Local IP country is resolved separately. Comparing it with the Public IP country helps identify different network paths and contributes to the IP Mismatch signal. Inidentification.scored, the address and country are returned in local_ip.ip and local_ip.country. An empty local_ip.ip means the address could not be obtained. History does not support searches by Local IP.
Country
The country associated with an IP address in this check. The public and local IP addresses each have their own country. Webhook:public_ip.country and local_ip.country.
Identifiers on a check
Session ID and Cookie ID describe a browsing session and browser storage. They do not name an entity.Session ID
A UUID for one browsing session. The snippet writes it tolocalStorage, and open tabs of your site share it. A new Session ID starts on the next page load after the last open page of your site is closed or navigated away from. Key: session_id.
Cookie ID
A UUID generated in the browser and stored in a first-party cookie andlocalStorage. It is lost when cookies or storage are cleared. Key: cookie_id.
Domain
The registered website scope for an identification and its results. Key:domain. History can also include site_domain, the registered site scope when supplied. Domain-scoped API keys restrict the results you can read. See Domains.
Browser
The detected browser family for an identification. Key:browser. It describes the observed environment; bot or AI attribution is returned separately.
Operating system
The detected operating system for an identification. Key:os. The operating-system mismatch and not-detected risk signals describe separate checks on this environment.
Device type
The detected device class, such as desktop or mobile. Key:device_type. It describes the kind of device, while Device ID distinguishes its observed identity.
Risk Score
A Risk Score and its risk band describe one identification. The current risk category describes a user, visitor, device or public IP over time. Risk signals and their weights explain the check. The risk value for one identification, from 0 to 100. Read the returned value instead of reconstructing it from signal weights. The separate value 999 indicates Banned IP: the address has been restricted for exceeding the request rate. Webhook field:data.risk_score. History field: score.
Risk band
The category for one identification’s Risk Score:
The analytics dashboard uses the same labels for the current risk category of a user, visitor, device or public IP, calculated from its identification history. See Risk scoring.
The scored webhook returns the numeric
data.risk_score. SDK helpers such as Node.js riskBand(score) can derive the label locally. The special value 999 for Banned IP is outside these three bands.
Trusted
The risk band for an identification with a Risk Score of 0–29. The observed check has low risk. Read the associated identity’s history and account events when the action also depends on account context. For a user, visitor, device or public IP, Trusted means its recorded identification history has not raised the current category. It does not mean all its checks scored 0. See current identity categories.Suspicious
The risk band for an identification with a Risk Score of 30–59. The check contains elevated-risk observations. Use its signals and the action’s context to choose an additional verification or review step. For a user, visitor, device or public IP, Suspicious means the share of suspicious identifications indicates elevated risk. The label summarizes that identity’s history, rather than requiring every check to be suspicious. See current identity categories.Dangerous
The risk band for an identification with a Risk Score of 60–100. The check contains high-risk observations. Review the signals and evidence before granting a sensitive action. The category describes this check, rather than establishing that an account has been compromised. For a user, visitor, device or public IP, Dangerous means the share of dangerous identifications indicates high risk. It takes priority when the history also qualifies as Suspicious. See current identity categories.Current risk category
The current risk category within a domain. It is calculated separately for Visitor ID (visitor_id), User HID (user_hid), Device ID (device_id) and public IP (public_ip). The labels are the same as the risk bands of one check: Trusted, Suspicious and Dangerous. The category describes accumulated risk for that key, rather than the Risk Score of one identification.
Use the category to assess the accumulated risk of a visitor, account, device or IP address. The calculation uses all available identifications within 90 days, rather than only those in the selected reporting period. The visitor, account, device and IP associated with one check can have different categories.
ShieldLabs calculates the share of checks with a Risk Score of 60 or more separately from the share scoring 30–59. If at least 5% of checks are dangerous, the category is Dangerous. Otherwise, if at least 5% are suspicious, the category is Suspicious. The remaining category is Trusted. The effect of one check depends on the total history size.
The anonymous value has no account risk category.
Neither webhooks nor the History API returns this category. It appears in Analytics and on the entity card. If there is no stored history, missing data is not displayed as Trusted.
Visitor risk
The current risk category based on identifications linked to the same Visitor ID within a domain. It summarizes the visitor’s activity over time, beyond the latest check.User risk
The current risk category of an account identified by its User HID within a domain. It considers the account’s identification history across its visitors, devices and IPs. Anonymous activity has no authenticated user risk.Device risk
The current risk category based on identifications linked to the same Device ID within a domain. A device can be associated with more than one visitor or account.IP risk
The current risk category based on identifications associated with the same public IP within a domain. It summarizes observed traffic from that address, which can be shared by several devices and accounts.Risk signal
A risk signal is a named result of a device, browser or network check. It explains which characteristic was found in this identification, beyond the final number. Signals distinguish, for example, VPN use, browser automation and a recognized bot so you can handle those cases differently. Some signals add weight to the Risk Score. Others report a fact with zero weight and do not increase it. Read the final value fromrisk_score: the server can cap a group’s contribution, so the sum of weights in signals does not always equal the result.
In an identification.scored webhook, detection_flags reports the detections and signals contains their names and weights. A dashboard label can group several related detections.
Signal weight
The contribution recorded for a detected risk signal in an identification’ssignals array. Each entry has name, the exported signal slug, and weight, its reported contribution. A weight is numeric; a detection flag is true or false. A zero-weight detection can still provide useful context. Use the returned Risk Score for the final result; weights are not independent scores to add across checks.
Detection flags
Boolean fields indata.detection_flags of a notification containing the calculated risk. A separate list is unnecessary here: these are the same detections listed in the signal catalog below.
Connection type
Theconnection_type field classifies one identification’s connection. A notification containing the calculated risk carries one of:
direct, mobile, vpn, proxy, tor, private_relay, unknown
Risk signals
The analytics dashboard displays signals under labels. When a label matches one signal, that signal appears directly below. When a label groups several signals, they are nested under it. See Risk Score for the difference between a risk signal, its weight and a detection flag.VPN
VPN is a signal that a virtual private network is being used. The service routes traffic through a VPN server, hiding the user’s original public IP. The site sees the service’s exit address. This signal also covers VPNs built into a browser or provided through an extension. ShieldLabs uses its own analytical research and network research data to identify VPNs. It compares IP information with network connection characteristics, STUN-check results and the browser time zone. This distinguishes VPN use from ordinary proxying. Inidentification.scored, the detection is returned in detection_flags.vpn. The webhook’s signals array lists this check’s signals and their weights: VPN uses name: "vpn" and weight: 30.
Proxy — dashboard label
Proxy is the dashboard label for a group of proxy detections, network-latency mismatches, Public IP and Local IP country differences, and operating-system inconsistencies. Proxies can change the visible IP or region, provide privacy, or route traffic. In abusive activity, they can evade restrictions and hide network connections between accounts. This group includes Proxy, Latency test, IP Mismatch and Operating System Mismatch. The label appears if at least one detection in the group fires. Read the individual results indetection_flags.
The signals array returns the individual signal weights. Their combined contribution to the Risk Score is capped at 60, even if the weights sum to more. The grouping itself adds no points.
On Overview, the Proxy tile shows a possible contribution of 30–60. An individual identification card shows the calculated contribution of the group.
Proxy — signal
Proxy is a signal that a request reaches the site through an intermediary server. ShieldLabs uses its own analytical and network research, combining IP information with evidence that the address belongs to proxy infrastructure. Inidentification.scored, the detection is returned in detection_flags.proxy. The webhook’s signals array lists this check’s signals and their weights: Proxy uses name: "proxy" and weight: 30.
Latency test
Latency test detects signs of an intermediary server through differences in network latency. ShieldLabs uses its own measurement method to compare TCP connection latency with the time required for a WebSocket exchange with the browser. A substantial difference can indicate an additional network segment between an intermediary server and the browser. The check takes several measurements of one connection and complements IP analysis. It helps detect signs of proxying even when network reference data does not identify the address as a proxy. Inidentification.scored, the detection is returned in detection_flags.latency_test. The webhook’s signals array lists this check’s signals and their weights: Latency test uses name: "latency_test" and weight: 60.
IP Mismatch
IP Mismatch detects signs of an intermediary server when the Public IP’s country differs from the country of the Local IP found by a browser network check. ShieldLabs runs its own WebRTC check: the browser opens a separate network path, exposing an address that can differ from the HTTP request’s address. This result is compared with a second independent network check. A difference between IP addresses alone is insufficient: the signal does not fire if their countries match. Both countries must be known. The check complements IP analysis and helps expose a different network exit even if network reference data does not identify the address as a proxy. The signal is not set when a VPN has already been detected. Inidentification.scored, the detection is returned in detection_flags.ip_mismatch. The webhook’s signals array lists this check’s signals and their weights: IP Mismatch uses name: "ip_mismatch" and weight: 45.
Operating System Mismatch
Operating System Mismatch detects an inconsistency between the operating system reported by the browser and the operating system visible from the network connection. ShieldLabs compares browser information with the OS family identified from the TCP/IP fingerprint of the connection that reaches its server. An intermediary server can terminate the TCP connection itself. The browser’s reported OS can then differ from the OS family identified from that server’s network characteristics. This mismatch indicates possible proxying or environment spoofing and helps detect an intermediary connection even when network reference data does not identify the IP as a proxy. The signal is not set when a VPN has already been detected. Inidentification.scored, the detection is returned in detection_flags.os_mismatch. The webhook’s signals array lists this check’s signals and their weights: Operating System Mismatch uses name: "os_mismatch" and weight: 60.
Private Relay
Private Relay is a signal that a private relay service, such as iCloud Private Relay, is being used. The service passes requests through intermediary infrastructure to hide the user’s original public IP. The site sees the service’s exit address. ShieldLabs uses its own analytical and network research to analyze the IP and evidence that it belongs to the service’s infrastructure. This distinguishes private relay use from ordinary proxying. Inidentification.scored, the detection is returned in detection_flags.private_relay. The webhook’s signals array lists this check’s signals and their weights: Private Relay uses name: "private_relay" and weight: 30. The corresponding connection_type value is private_relay.
Tor Network
Tor Network is a signal that a request arrived through a Tor exit node. Tor routes traffic through a chain of nodes to hide the user’s original public IP. The site sees the exit node’s address. ShieldLabs uses its own analytical and network research to analyze the IP and evidence that it belongs to a Tor exit node. This distinguishes Tor from ordinary proxying. Inidentification.scored, the detection is returned in detection_flags.tor. The webhook’s signals array lists this check’s signals and their weights: Tor Network uses name: "tor" and weight: 99. The corresponding connection_type value is tor.
Check Incomplete — dashboard label
Check Incomplete is the dashboard label for a group of incomplete-check detections. It indicates that some checks did not finish or that the data was insufficient to identify certain environmental characteristics. Incompleteness alone does not establish proxying or environment spoofing. This group includes Check Incomplete, Network Check Incomplete and Operating System Not Detected. The label appears if at least one detection in the group fires. Read the individual results indetection_flags.
The signals array returns the individual signal weights. Their combined contribution to the Risk Score is capped at 30, even if the weights sum to more. The grouping itself adds no points.
On Overview, the Check Incomplete tile shows a possible contribution of 0–30. An individual identification card shows the calculated contribution of the group.
Check Incomplete — signal
Check Incomplete indicates that ShieldLabs did not receive expected browser data required for the device fingerprint, or received an error while collecting it. The check is saved with the available information. The signal has zero weight and does not increase the Risk Score. It is suppressed for recognized good bots. Inidentification.scored, the detection is returned in detection_flags.check_incomplete. The webhook’s signals array lists this check’s signals and their weights: Check Incomplete uses name: "check_incomplete" and weight: 0.
Network Check Incomplete
Network Check Incomplete indicates that ShieldLabs had not received confirmation of a successful STUN network check when it calculated the result. The browser sends a separate UDP STUN request to ShieldLabs, independently of HTTP, to check another network path and expose the address on it. If the exchange is unconfirmed, possible causes include network restrictions, blocked UDP, browser settings or connection interference. Missing confirmation alone does not establish proxying. The signal is not set when a VPN has already been detected. Inidentification.scored, the detection is returned in detection_flags.network_check_incomplete. The webhook’s signals array lists this check’s signals and their weights: Network Check Incomplete uses name: "network_check_incomplete" and weight: 30.
Operating System Not Detected
Operating System Not Detected indicates that ShieldLabs could not identify the OS family from browser information or the connection’s TCP/IP fingerprint. Without that information, the reported OS cannot be compared with the network characteristics. Possible causes include insufficient data, environmental characteristics, or interference with the browser or network connection. The signal does not establish the cause. The signal is not set when a VPN has already been detected. Inidentification.scored, the detection is returned in detection_flags.os_not_detected. The webhook’s signals array lists this check’s signals and their weights: Operating System Not Detected uses name: "os_not_detected" and weight: 30.
Anti-Detect Browser
Anti-Detect Browser is a signal of an anti-detect browser or device fingerprint spoofing. An anti-detect browser presents altered device and browser characteristics so a site cannot associate the visit with the original environment. ShieldLabs uses its own analytical research and technical signatures to compare characteristics from different components of the browser environment. When WebGL and WebGPU are available, the check compares the GPU vendor and architecture, reported hardware and graphics capabilities. It also analyzes characteristic environmental behavior. These comparisons help detect masking even when the reported browser characteristics have changed. Inidentification.scored, the detection is returned in detection_flags.anti_detect_browser. The webhook’s signals array lists this check’s signals and their weights: Anti-Detect Browser uses name: "antidetect_browser" and weight: 60.
Banned IP
Indicates that an address has been restricted for exceeding the request rate. It appears as the value 999 in the Risk Score, rather than as ordinary points. Key:banned_ip.
Incognito mode
Indicates that the check ran in a private browsing mode. Adds 0 to the Risk Score. Key:incognito.
Good bot — dashboard label
Good bot is the dashboard label for recognized search bots, AI bots and AI browsers. The group accounts for recognized search and AI traffic separately from suspicious automation and environment spoofing. It includes Search bot, AI Bot and AI Browser. The label appears if at least one detection in the group fires. Read the individual results fromdetection_flags.search_bot, detection_flags.ai_bot and detection_flags.ai_browser. There is no separate webhook flag for the group.
The signals array returns the individual signal weights. All three detections have zero weight. A recognized check receives a Risk Score of 0. Accompanying masking, automation and incomplete-check signals are suppressed. The grouping itself adds no points.
On Overview, these visits are counted separately from risky visitors. The identification card shows the specific detection. If the provider is known, its name is returned in search_bot_owner, ai_bot_owner or ai_browser_owner and displayed beside the detection.
AI bots
AI bots is a signal of a recognized AI bot: a program that retrieves site pages for artificial-intelligence tasks. It can collect content or request a page to prepare an answer for someone. Browsers with AI functionality belong to the separate AI Browser signal. ShieldLabs recognizes supported clients from the name presented in the request. Some supported clients can also be recognized through published provider IP addresses. AI search bots belong to Search bot. A client name alone does not prove that the request came from the named provider. Inidentification.scored, the detection is returned in detection_flags.ai_bot. The webhook’s signals array lists this check’s signals and their weights: AI bots uses name: "ai_bot" and weight: 0. If the provider is known, its name is returned in ai_bot_owner. The dashboard groups the signal under Good bot. A recognized check receives a Risk Score of 0, and accompanying masking, automation and incomplete-check signals are suppressed.
Search bot
Search bot is a signal of a recognized search crawler that visits site pages for indexing. It also includes supported bots that index pages or collect content when they are not classified as AI bots or AI Browser. AI search bots belong to Search bot. ShieldLabs recognizes supported clients from the name presented in the request. For some search bots, it also uses network information, comparing IP ownership data with the bot name or the address’s organization. A client name alone does not prove that the request came from the named provider. Inidentification.scored, the detection is returned in detection_flags.search_bot. The webhook’s signals array lists this check’s signals and their weights: Search bot uses name: "search_bot" and weight: 0. If the provider is known, its name is returned in search_bot_owner. The dashboard groups the signal under Good bot. A recognized check receives a Risk Score of 0, and accompanying masking, automation and incomplete-check signals are suppressed.
AI browser
AI browser is a signal of a supported browser platform through which a program can open pages, navigate a site and perform actions. A client that only retrieves pages to prepare an answer or collect content belongs to AI bots instead. ShieldLabs sets the signal after successfully verifying a cryptographic request signature against the platform’s keys. The signature establishes that the visit uses the platform’s infrastructure. A reported browser name is insufficient, as is provider information without confirmation of the platform’s infrastructure. The signature attributes the visit to the platform, rather than the person or model controlling it. Inidentification.scored, the detection is returned in detection_flags.ai_browser. The webhook’s signals array lists this check’s signals and their weights: AI browser uses name: "ai_browser" and weight: 0. If the provider is known, its name is returned in ai_browser_owner. The dashboard groups the signal under Good bot. A recognized check receives a Risk Score of 0, and accompanying masking, automation and incomplete-check signals are suppressed.
Timezone Mismatch
Indicates that the browser’s time zone is inconsistent with the location of the public IP. Adds 10 to the Risk Score. Key:timezone_mismatch.
Bad bot — dashboard label
Bad bot is the dashboard label for suspicious automation and environment spoofing. It indicates signs of programmatic browser control, altered device characteristics, or unavailable browser capabilities required for the check. This group includes Browser Automation, Device spoofing and JavaScript Disabled. The label appears if at least one detection in the group fires. Read the individual results indetection_flags.browser_automation, detection_flags.device_spoofing and detection_flags.javascript_disabled. There is no separate webhook flag for the group.
The signals array returns the individual signal weights. Each of the three detections has a weight of 90. Their combined contribution to the Risk Score is capped at 90, even if the weights sum to more. The grouping itself adds no points. Other signals retain their contributions to this check.
On Overview, the Bad bot tile shows a contribution of 90. These visits are counted separately from other visitors. An individual identification card shows the calculated contribution of the group.
Browser Automation
Indicates that the browser is controlled by automation rather than a person. Adds 90 to the Risk Score. Key:browser_automation.
Device spoofing
Device spoofing detects altered device characteristics. ShieldLabs compares the reported operating system, browser and hardware with other evidence from the same environment: graphics, platform, fonts, voice components, browser audio-system parameters and the TLS connection fingerprint. The signal fires when these characteristics contradict each other and do not match the reported device. An ordinary difference between characteristics alone does not trigger it. One or more contradictions produce one Device spoofing signal with a weight of 90. Additional contradictions do not increase its weight. Inidentification.scored, the detection is returned in detection_flags.device_spoofing. The webhook’s signals array lists this check’s signals and their weights: Device spoofing uses name: "device_spoofing" and weight: 90. The dashboard groups the signal under Bad bot, whose combined contribution is capped at 90.
JavaScript Disabled
Indicates that JavaScript or required page capabilities are unavailable in the browser. Adds 90 to the Risk Score. Key:javascript_disabled.
AI traffic
AI agents and assistants describe how an AI application works. The AI Bot and AI Browser signals describe the supported traffic ShieldLabs recognizes.AI agent
An AI application that plans and performs tasks on someone’s behalf, such as navigating pages or completing a form. An agent can control a browser or retrieve content directly. ShieldLabs reportsai_browser when it recognizes a supported AI browser platform; a recognized AI bot or crawler uses ai_bot. These signals identify the detected client category, rather than the person or AI model controlling it. See AI agent detection.
AI assistant
An AI application that answers questions, summarizes information or helps with a task. It can request pages from your website to prepare an answer. ShieldLabs recognizes supported assistant retrieval traffic through theai_bot signal; activity through a supported AI browser platform can use ai_browser. An assistant can also perform agent-like tasks, so the application name alone does not determine the signal. Read the provider and identity evidence alongside the detection. See AI assistant detection.
High-Risk Events
High-Risk Events describe account activity across identifications. A scored webhook can include three account-event evaluations inhre; multi-accounting uses its own group-change event.
High-Risk Event
A High-Risk Event is an event ShieldLabs detects using more than 47 rules and heuristics, comparing device, browser and network characteristics with account history. There are four event types: Multi-accounting, Account sharing, Impossible travel and Account takeover. A detected event receives Medium or High confidence. This reflects the system’s confidence in the detection and is assessed separately from the Risk Score of an individual check. Pass the same User HID when checking the same authenticated account. Events and their supporting evidence are available in the analytics dashboard: open the account card to inspect event clusters and connection graphs. Account sharing, Impossible travel and Account takeover results are delivered inidentification.scored. Multi-account group changes use the separate hre.multi_account.changed webhook, which requires additional enablement. See High-Risk Events.
Cluster
A cluster is a group of related accounts, devices or checks that ShieldLabs automatically forms using its own matching algorithms, rules and heuristics. Connections are identified using ShieldLabs’ device fingerprinting technology, browser and network characteristics, and account history. A cluster’s contents depend on the event. For Multi-accounting, it shows related accounts; for Account sharing, devices used by one account. For Impossible travel, it shows the compared checks, distance and time between them. For Account takeover, it shows the current check and the historical observations used to detect the event. A cluster explains the detection: which connections or changes were found and which data supports the result. In the analytics dashboard, open an account card by User HID, select an event cluster and inspect its connection graph. See High-Risk Event clusters.Cluster ID
The identifier of a High-Risk Event cluster. Use it to associate information and updates that belong to the same cluster. In an event result insideidentification.scored, cluster_id can be null because no cluster reference was supplied. This does not, by itself, cancel the detection: interpret the result using status and level.
In hre.multi_account.changed, cluster_id identifies a multi-account group. The identifier stays the same when the group’s membership expands or contracts unambiguously. A split or merge can resolve previous clusters and create new clusters with different identifiers.
Use event_id to recognize a repeated delivery and revision to order changes to one group.
Multi-account group creation and updates
The creation, membership changes and resolution described here use theaction field of hre.multi_account.changed.
A multi-account group is created when a complete recalculation assembles an account group that did not previously exist, or when a previously resolved group becomes active again. This episode receives a new cluster_id. ShieldLabs sends hre.multi_account.changed with action: "detected", detected: true, level: "medium" or "high", and previous_revision: null. Both user_hids and added_user_hids contain the complete current membership. removed_user_hids is empty.
An account leaves a continuing group when the membership reduction is unambiguous: the remaining members still form the same group. The cluster_id stays the same. The event has action: "updated"; removed_user_hids lists the accounts removed by this change, and user_hids lists the current membership. This difference applies only to that notification. The next message does not repeat those removals, and there is no separate list of every account ever removed.
An unambiguous membership expansion also uses action: "updated", with new accounts in added_user_hids. If membership stays the same but confidence or the rules version changes, ShieldLabs also sends updated with the same cluster_id. Both change lists are empty in that case.
Multi-account group resolution, splits and merges
An account’s connection to a multi-account group remains for 90 days after its last observation on a shared characteristic. When a complete recalculation finds too few remaining members for the group to continue, the previouscluster_id is resolved. ShieldLabs sends hre.multi_account.changed with the same cluster_id, action: "resolved", detected: false and level: null.
Both user_hids and removed_user_hids contain the entire former membership, rather than one removed account. The notification is sent on the next complete recalculation if hre.multi_account.changed delivery is enabled. An incomplete calculation does not send a resolution. No separate updated message with a single removed account is sent in this case.
The same resolution is sent when a complete recalculation no longer confirms the previous group for another reason. An account from a resolved cluster can remain in another active cluster: inspect the state of each active cluster_id separately.
When a split or merge prevents an unambiguous continuation of the previous group, each replaced cluster sends its own resolved notification. Resulting groups send separate detected notifications and receive different cluster_id values. A new group’s notification does not include the previous identifier. These notifications are independent and can arrive in any order. Recalculating the same membership, confidence and rules version does not create another notification.
Account-sharing clusters
An Account sharing cluster contains devices used by one authenticated account. Devices observed on that account during the last 90 days are counted. A new device enters the cluster on the check where it appears. The result is delivered inidentification.scored, under account_sharing, with a cluster_id when a cluster reference has been published. Account sharing has no separate webhook.
A device stops counting 90 days after its last visit. No notification is sent at that moment. If the event no longer qualifies after the device is removed, the stored result is recalculated without an identification and without a cluster_id.
The account’s next check sends an ordinary identification.scored event for that check, with its current result in account_sharing. If Account sharing is no longer confirmed, status is evaluated and both level and cluster_id are null. The previous cluster_id is not included. Null level and cluster_id mean no active Account sharing result was found on this check.
If Account sharing remains confirmed and a cluster reference is published, the cluster_id corresponds to the new membership. After the device set changes, the next published reference has a different identifier.
Impossible-travel clusters
An Impossible travel cluster contains two checks of one authenticated account: the previous check and the current check. The identifier is calculated from that pair. Each new pair receives its owncluster_id.
The result is delivered in identification.scored, under impossible_travel, with a cluster_id when the event is confirmed. There is no separate webhook. The pair’s membership does not change over time, and no member-removal or cluster-resolution notification is sent. If no event is found on a check, level and cluster_id are null. The previous cluster_id is not included in that notification.
Account-takeover clusters
An Account takeover cluster contains the current check and the authenticated account history used for comparison. It does not assemble a group of other accounts. A cluster is created when the check detects the event. A return visit from an already familiar device does not, by itself, create a new cluster. The result is delivered inidentification.scored, under account_takeover, with a cluster_id when a cluster reference has been published. There is no separate webhook. Member removal and resolution after 90 days do not apply here. If no event is found on a check, level and cluster_id are null. The previous cluster_id is not included in that notification.
Multi-accounting
Multi-accounting detection identifies related accounts on the same site. ShieldLabs uses more than seven rules and heuristics developed by our data analytics team. They compare digital identifiers, device and network characteristics, and account activity history. Cluster. ShieldLabs’ system completely reassesses connections between all authenticated accounts on one site at least once every 10 minutes to detect Multi-accounting. Group changes are delivered through the separatehre.multi_account.changed webhook: a group is detected, updated or resolved. This webhook requires additional enablement.
Main signals. IP, Cookie and Device ID. ShieldLabs recognizes devices using its own Hardware ID technology, which analyzes hardware characteristics and helps match activity from one device across browser changes. Browser and operating system are additional characteristics.
Confidence. Medium and High reflect confidence in the connection between accounts. The level depends on the combination and consistency of the evidence.
Display threshold. In the analytics dashboard, select the minimum number of related accounts to display for an event, starting at three.
Connection graph. Open the user card by User HID to inspect related accounts and the data used to connect them into a cluster.
Account sharing
Account sharing detection identifies one account being used on different devices. ShieldLabs uses more than 10 rules and heuristics to detect Account sharing and reduce false positives. Cluster. Clusters are built only for authenticated accounts. Devices observed on the account in the last 90 days are counted. A new device being added to the account is the event. The result is delivered in that check’s webhook when the new check occurs. Account sharing has no separate webhook. Main signals. IP, Cookie and Device ID. Device ID uses ShieldLabs’ own Hardware ID technology, which analyzes device hardware characteristics. Browser and operating system are additional characteristics. Multiple browsers on one physical device count as one device to reduce false positives. Confidence. Medium and High depend on the system’s confidence that different devices are being used to access the account. Display threshold. In the analytics dashboard, select the minimum number of different devices to display for an event, starting at four. Connection graph. The account card, identified by User HID, provides a dashboard graph of the account’s devices and the evidence used to group them into a cluster.Impossible travel
Impossible travel detection identifies an account appearing in two places so far apart and so close in time that one person could not have traveled between them. ShieldLabs uses more than 10 rules and heuristics to detect Impossible travel and reduce false positives. Cluster. This event does not create a group of other accounts. It evaluates only the authenticated account. The event consists of two clean checks for that account, no more than 48 hours apart, whose distance and timing are inconsistent with travel. The signal appears whenever such a pair occurs and is delivered in the new check’s webhook. There is no separate webhook. If VPN, Proxy, Tor or Private Relay is detected, no Impossible travel event is created. Main signals. Address coordinates, time between checks, Cookie and Device ID. Device ID uses ShieldLabs’ own Hardware ID technology to analyze hardware characteristics. Browser and operating system also contribute to this comparison. A recognized same-device result is not shown as travel even if the mapped country changes, so geolocation errors and network changes are not mistaken for movement. Two different cookies that had already appeared on the account by the time of their respective checks count as two devices. Confidence. Medium or High requires a distance of at least 300 km and a speed above 800 km/h. High requires different devices plus additional supporting evidence: a speed above 1,000 km/h over at least 500 km, both checks within a 30-minute window, or a country change. If the devices cannot be compared, confidence is no higher than Medium. Connection graph. The account card, identified by User HID, provides a dashboard graph of the account and the two checks used for the event. Each evaluation of a qualifying pair forms a separate cluster.Account takeover
Account takeover detection identifies an account visit that differs from its usual activity and may indicate access by another person. ShieldLabs uses more than 20 rules and heuristics. They compare environmental changes with account history and help reduce false positives. Cluster. The event belongs to an authenticated account and does not form a group of other accounts. The check compares the current visit with account history in sequence, considering conditions that support or exclude the event. If the device is recognized as familiar from the available account history, a country or network change alone does not trigger Account takeover. If a visit from a new device meets the detection conditions, ShieldLabs creates an event card. Subsequent visits from an already familiar device do not, by themselves, create another event. A detected result is delivered in the current check’s webhook. There is no separate Account takeover webhook. Main characteristics. Device, Cookie, the account’s operating-system, country and IP history, and indicators of connection or browser masking. ShieldLabs uses its own Hardware ID technology to analyze hardware characteristics for device recognition. Changing browsers on the same recognized device does not, by itself, trigger Account takeover. Confidence. Medium and High reflect confidence in the event. The level depends on the combination of device, browser-context and network changes relative to account history. Connection graph. The user card, identified by User HID, provides a dashboard graph of the current check and the historical observations used in the evaluation.Medium / High confidence
Medium and High are confidence levels for a High-Risk Event. The level depends on the combination and consistency of supporting evidence. Interpret the evidence in the context of the event type: Multi-accounting, Account sharing, Impossible travel or Account takeover. A larger number of accounts or devices does not, by itself, explain High confidence. Confidence belongs to that event and is returned inlevel. It is separate from the 0–100 Risk Score of one check.
Analytics
Dashboard views and metrics for investigating traffic and identities. Read each metric’s scope: selected-period activity and current risk describe different things.Analytics dashboard
The dashboard for investigating traffic, identities and account events, as well as managing integration and billing. The AI assistant is currently marked soon. Start with Dashboard overview.Entity card
The analytics dashboard view for one user, visitor, device or public IP. It combines the current risk category, activity, linked identifiers and available event evidence. The selected period controls the activity shown; the current risk category has its own scope. See Entity cards.Identification card
The analytics dashboard view for one check. It shows that identification’s Risk Score, signals, identifiers, device, network and traffic source. See Identification card.Traffic quality
Traffic quality is an aggregate traffic-risk metric on a 0–100 scale. A lower value means the checked traffic had less risk. The metric describes the selected period, and comparison with the previous period helps reveal changes in traffic quality. On Overview, the metric covers the selected domain or all domains in the account. It is also available by country, browser, operating system, connection type, channel and device type to help identify higher-risk traffic groups. Select a row to open the matching identifications in Analytics, then inspect individual Risk Scores and detected signals. ShieldLabs calculates the metric from the distribution of identifications across Risk Score bands. A check scoring 60 or more receives full weight; a check scoring 30–59 receives half weight. Checks below 30 do not increase the weighted sum but are included in the total number of checks. A weighted sum equal to half the total number of checks corresponds to the top of the scale, 100. The result is capped at 100 and rounded to a whole number. It describes the concentration of risk across checks, rather than the percentage of dangerous visitors. Read the metric together with the number of checks. If the selected scope contains no checks, the metric is 0. Risk Score describes one identification. Current identity categories and High-Risk Event confidence are calculated separately. Traffic quality is available in the dashboard; neither webhooks nor History returns it.Identifications
The number of identifications in the selected period.Unique visitors
The number of distinct Visitor IDs in the selected period. It is not an exact count of people.Risky visitors
The combined count: Suspicious visitors + Dangerous visitors in the selected scope. In the Overview visitor breakdown, recognized Good bots and Bad bots are counted separately from the human visitor split. See Unique visitors.Risky users
The combined count: Suspicious users + Dangerous users, based on each user’s current risk category. The High-Risk Event count is a separate measure and may overlap.High-Risk Event users
Users with recorded positive evidence of a High-Risk Event during the selected period. The dashboard indicates where coverage is incomplete and where the count is a lower bound.Analytics chart
The trend in identifications, unique visitors, users, devices or public IPs over the selected period, split by risk band. The time bucket size depends on the period length.Traffic attribution
Where traffic comes from and how it is grouped in reports.Traffic Source
Where an identification came from: the resolved channel, referrer domain, landing URL and UTM parameters. Webhook key:traffic_source. History rows also have a broader channel group. The analytics dashboard ranks channels, sources and campaigns by the risk of the traffic they bring.
Channel
The resolved acquisition channel of an identification: Google Ads, Meta, TikTok, LinkedIn, X, Pinterest, Microsoft Ads, Organic Search, Search bot, Referral, Direct or Other. Here, Search bot describes the origin of a visit, not a risk signal. History rows also have a broader channel group: Paid Search, Paid Social, Social, Organic, Bot, Referral, Direct or Other.UTM parameters
Theutm_source, utm_medium, utm_campaign, utm_content and utm_term values from the inbound URL. They are captured on each identification for source attribution and shown in the dashboard and exports.
Referrer domain
The domain of the referring page used for traffic attribution. Key:referrer_domain; in a scored webhook it is inside traffic_source. It can be empty when no referrer is available.
Landing URL
The page URL recorded as the entry point for an identification’s traffic attribution. Webhook:traffic_source.landing_url. History: entry_url.
Channel group
A broader grouping of a resolved traffic channel. History key:traffic_channel_group; the specific channel is traffic_channel. traffic_reason, when supplied, gives context for the attribution.
Click ID type
The type of click identifier recognized for traffic attribution. Webhook:traffic_source.click_id_type. History: click_id_type. The field describes attribution metadata, not a separate risk signal.