Skip to main content
ShieldLabs uses different models for a scored identification, a multi-account group and a History row. Choose by event_type and schema_version; do not assume that every response has an Identification ID or a Risk Score. For definitions of individual fields, start with the product glossary for identifiers and risk signals, or the integration glossary for webhook envelopes, revision, level, kind, client identity and API terms.

​
WebhookEvent

The signature is in the X-Shield-Signature header, not the JSON body. Verify the raw bytes before trusting any field.

​
Scored identification

identification.scored contains the identification’s IDs, user, IPs, device information, traffic attribution, score, signal contributions, detection flags and three per-identification High-Risk Event results. The complete field list and example are maintained in one place: Webhook reference.
  • identification_id joins the result to a check; event_id deduplicates delivery.
  • observed_at is the original observation time; created_at is event creation time.
  • risk_score is authoritative. A weight sum is not a substitute.
  • hre holds Account sharing, Account takeover and Impossible travel. Multi-accounting has a separate event.

​
Detection flags

data.detection_flags in an identification.scored webhook contains these 20 boolean keys. The weight belongs to the corresponding risk signal; the flag itself is true or false. Use the returned risk_score as the final result. These are webhook keys. History rows expose a smaller set of flags under their own field names; see Response contracts. Read signals for the contributions returned with a check.

​
WebhookSignal

One score contribution in data.signals:
name is the exported signal slug; weight is its reported contribution. Read boolean decisions from detection_flags. See signal names and weights.

​
High-Risk Events

For the per-identification results, read status before level: A detected result has level: "medium" or "high". An optional cluster reference links it to a published group. Do not invent a cluster ID from a request or device ID. The multi-account group contract instead carries action, cluster_id, members and revisions. It has no identification risk_score.

​
History row

The History API returns { "data": [...], "total": N }. Rows use snake_case and represent stored identifications. The API’s projection and available fields can differ from a webhook version. The webhook column is relative to data; its envelope has a separate created_at. History includes selected flags and optional attribution fields, rather than every field in a scored webhook. Response contracts explains these mappings and SDK normalization. See Search identification history for pagination, authentication and examples.

​
Identity and context

These fields are present on every History row unless marked optional. For the claims and verification fields inside client_identity, see Client identity. The object separates a recognized name from evidence-supported attribution. AI detection explains how to use it with the bot flags.

​
Traffic attribution

These fields are optional and omitted when empty or false.

​
Profile

Get domain profile returns the registered Domain, remaining account volume in Weight, masked PublicKey and Secret, and CreatedAt. Manage webhook endpoints under Integration > Webhooks.

​
Machine-readable schema

Download the OpenAPI bundle for endpoint schemas. For webhooks, select the model by the received event_type and schema_version.