Risk signals

Risk signals let you feed fraud-detection data into Truthlocks from any upstream provider — device fingerprinting services, IP reputation APIs, email verification tools, document analysis engines, or your own internal rules. Once ingested, signals are available through the API and the Risk & Fraud > Signals page in the console.

The Anti-Fraud Identity Firewall is generally available. All five detection paths — direct signal ingestion, event normalization, deepfake scanning, ATO detection, and velocity scoring — are production-ready with multi-language API examples (cURL, JavaScript, Python), end-to-end guides, and real-time webhook notifications for all signal types. Automated risk decisions, case management, and fraud SIEM export are now available.

You can create signals in five ways:

Direct ingestion — send a fully scored signal via POST /v1/risk/signals when you already have a risk score from an external provider. Supports idempotent retries via the Idempotency-Key header.
Event normalization — send a raw identity event via POST /v1/risk/events and let the platform map it to a signal type and base score automatically. See event normalization.
Deepfake and impersonation scanning — submit subjects for automated analysis via POST /v1/risk/deepfake/scan. Scans that score 60 or above automatically ingest a risk signal. See the deepfake detection guide.
Account takeover detection — evaluate login events against velocity-based heuristics via POST /v1/risk/ato/evaluate. Alerts are created and risk signals ingested automatically when thresholds are crossed. See the ATO detection guide.
Velocity and anomaly scoring — record subject actions via POST /v1/risk/velocity/record and have the platform track frequency across rolling time windows (1 m, 5 m, 1 h, 24 h). Actions that produce a weighted velocity score of 60 or above automatically ingest a risk signal. See the velocity scoring guide.

Choosing an ingestion path

Scenario	Use	Endpoint
You have a risk score from an external fraud tool	Direct ingestion	`POST /v1/risk/signals`
You want platform-native events (failed logins, deepfake detections) scored automatically	Event normalization	`POST /v1/risk/events`
You want to scan a subject for deepfake manipulation or impersonation	Deepfake scan	`POST /v1/risk/deepfake/scan`
You want to detect account takeover attempts based on login velocity	ATO detection	`POST /v1/risk/ato/evaluate`
You want to detect velocity anomalies across any action type	Velocity scoring	`POST /v1/risk/velocity/record`
You use multiple signal sources	All five — signals land in the same pipeline	Any endpoint

All five paths produce the same risk signal records. You can query, filter, and review signals from any path using the list endpoint and the Risk & Fraud > Signals console page.

How it works

Ingest signals

Send a POST request to /v1/risk/signals with the signal source, type, risk score, and the subject it relates to. Attach any extra context in the payload object.

Query and filter

Use GET /v1/risk/signals to list signals with filters for source, signal type, subject, and minimum score. Results are paginated with cursor-based pagination.

Review in the console

Open Risk & Fraud > Signals in the tenant console to browse signals, filter by source or score, and inspect individual signal details.

Prerequisites

An active Truthlocks tenant with an API key
At least one upstream fraud-detection source that produces scored signals

Ingesting a signal

Send a POST request with the required fields:

curl -X POST https://api.truthlocks.com/v1/risk/signals \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "signal_source": "external",
    "signal_type": "velocity",
    "risk_score": 85,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f",
    "payload": {
      "ip": "203.0.113.42",
      "country": "US",
      "reason": "multiple_accounts_same_device"
    },
    "ip_address": "203.0.113.42"
  }'

const response = await fetch("https://api.truthlocks.com/v1/risk/signals", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    signal_source: "external",
    signal_type: "velocity",
    risk_score: 85,
    subject_type: "user",
    subject_id: "usr_8f14e45f",
    payload: {
      ip: "203.0.113.42",
      country: "US",
      reason: "multiple_accounts_same_device",
    },
    ip_address: "203.0.113.42",
  }),
});
const signal = await response.json();

import httpx
import uuid

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/signals",
    headers={
        "X-API-Key": "tl_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "signal_source": "external",
        "signal_type": "velocity",
        "risk_score": 85,
        "subject_type": "user",
        "subject_id": "usr_8f14e45f",
        "payload": {
            "ip": "203.0.113.42",
            "country": "US",
            "reason": "multiple_accounts_same_device",
        },
        "ip_address": "203.0.113.42",
    },
)
signal = resp.json()

Required fields

Field	Type	Description
`signal_source`	string	Origin of the signal — `verification`, `login`, `attestation`, `external`, or `manual`
`signal_type`	string	What was detected (e.g. `velocity`, `geo_anomaly`, `device_fingerprint`, `behavior`, `deepfake`, `ato`, `impersonation`)
`risk_score`	integer	Risk score from `0` (safe) to `100` (high risk). Scores at or above 80 trigger automatic review.
`subject_type`	string	Type of entity: `user`, `issuer`, `attestation`, `session`, `ip`, or `device`
`subject_id`	string	Identifier of the entity being evaluated

Optional fields

Field	Type	Description
`payload`	object	Arbitrary JSON with signal-specific context (IP addresses, geolocation, reasons)
`ip_address`	string	Source IP address associated with this event
`user_agent`	string	User-Agent string associated with this event

Idempotency

Include an Idempotency-Key header (UUID) to prevent duplicate signals during retries. If you send the same key twice, the duplicate is silently ignored.

Querying signals

List with filters

curl "https://api.truthlocks.com/v1/risk/signals?source=external&min_score=50&limit=25" \
  -H "X-API-Key: tl_live_..."

Available filters:

Parameter	Description
`source`	Filter by signal source
`signal_type`	Filter by signal type
`subject_type`	Filter by subject type
`subject_id`	Filter by subject ID
`min_score`	Minimum score threshold (0–100)
`limit`	Results per page (max 100)
`cursor`	Cursor for next page

Get a single signal

curl https://api.truthlocks.com/v1/risk/signals/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: tl_live_..."

Console view

The Risk & Fraud > Signals page in the console provides a searchable, filterable list of all ingested signals. Each row shows the source, type, score (color-coded by severity), subject reference, and timestamp. Use the filters at the top of the page to narrow results by source, signal type, or minimum score. Click any row to view the full signal details including the payload metadata object.

Scoring guidelines

Consistent scoring across sources makes downstream analysis more reliable. We recommend the following ranges:

Range	Interpretation	Example
0 – 30	Low risk	Known good device, reputable IP
30 – 60	Moderate risk	VPN usage, new account velocity
60 – 80	High risk	Disposable email, datacenter IP
80 – 100	Critical risk	Known fraud device, impossible travel

Scores at or above 80 trigger automatic review decisions. Score interpretation beyond the automatic threshold is up to you — the platform stores and returns scores as-is and does not normalize across sources.

Event normalization

Instead of manually constructing risk signals, you can submit raw identity events and let the platform normalize them into signals automatically. This is useful when you want to feed platform-native events — failed logins, invalid signatures, deepfake suspects — directly into the risk pipeline without mapping them to signal types yourself. Send a POST request to /v1/risk/events with the event source, type, and subject:

curl -X POST https://api.truthlocks.com/v1/risk/events \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_source": "login",
    "event_type": "login.failed.repeated",
    "subject_id": "user_abc123",
    "ip_address": "198.51.100.42",
    "payload": { "attempt_count": 8, "window_seconds": 120 }
  }'

const response = await fetch("https://api.truthlocks.com/v1/risk/events", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event_source: "login",
    event_type: "login.failed.repeated",
    subject_id: "user_abc123",
    ip_address: "198.51.100.42",
    payload: { attempt_count: 8, window_seconds: 120 },
  }),
});
const result = await response.json();

import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/events",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "event_source": "login",
        "event_type": "login.failed.repeated",
        "subject_id": "user_abc123",
        "ip_address": "198.51.100.42",
        "payload": {"attempt_count": 8, "window_seconds": 120},
    },
)
result = resp.json()

The response includes both the raw event_id and the normalized signal_id, so you can trace the full pipeline from event to signal:

{
  "event_id": "2a4b6c8d-...",
  "signal_id": "9f3a1c2d-...",
  "event_type": "login.failed.repeated",
  "signal_type": "ato",
  "risk_score": 70,
  "normalized": true,
  "created_at": "2027-05-01T10:00:00Z"
}

When normalized is true, the event matched a known mapping. When false, the platform used the generic fallback.

Built-in event mappings

The platform ships with pre-calibrated mappings for common identity events:

Event type	Signal type	Base score
`verification.failed`	behavior	60
`verification.invalid_sig`	behavior	75
`login.failed.repeated`	ato	70
`login.suspicious_geo`	geo_anomaly	65
`attestation.deepfake_suspect`	deepfake	85
`session.hijack_suspect`	ato	90

Unknown event types are accepted with signal type behavior and a base score of 10.

Event fields

Required:

Field	Type	Description
`event_source`	string	System that generated the event — `attestation`, `verification`, `login`, or `consumer_portal`
`event_type`	string	Raw event name (e.g. `login.failed.repeated`, `attestation.deepfake_suspect`)
`subject_id`	string	Identifier of the entity involved in the event

Optional:

Field	Type	Description
`event_ref_id`	string	External reference ID (attestation ID, session ID) for cross-referencing
`ip_address`	string	Source IP address
`payload`	object	Raw event payload for enrichment context

Use event normalization when your events originate from within the platform (logins, verifications, attestations). Use the direct signal ingestion endpoint when you already have a scored signal from an external source.

Tenant isolation

Risk signals are fully tenant-isolated using row-level security (RLS). Each signal is bound to the authenticated tenant at ingestion time, and queries can only return signals that belong to the calling tenant.

Deepfake and impersonation detection

The deepfake detection API extends the risk signal pipeline with automated scanning for manipulated content and identity fraud. Submit images, videos, documents, or attestations for analysis, and scans that exceed the risk threshold automatically create a risk signal — no extra API call needed. See the deepfake and impersonation detection guide for the full workflow, indicator reference, and code examples.

Account takeover detection

The ATO detection API extends the risk signal pipeline with velocity-based login monitoring. Send login events to POST /v1/risk/ato/evaluate and the platform tracks failed attempts per subject in a rolling one-hour window. When a subject crosses a threshold (5, 10, or 20 failed logins), an alert is created and a risk signal is automatically ingested — no extra API call needed. See the account takeover detection guide for the full workflow, threshold reference, and integration patterns.

Velocity and anomaly scoring

The velocity scoring API extends the risk signal pipeline with multi-window action tracking and anomaly detection. Record any subject action via POST /v1/risk/velocity/record and the platform tracks frequency across four rolling windows (1 m, 5 m, 1 h, 24 h). A weighted velocity score is computed from the window counts, biased toward short windows for burst detection. When the score reaches 60 or above, a risk signal with signal_type: "velocity" is automatically ingested — no extra API call needed. See the velocity and anomaly scoring guide for the full workflow, scoring model, and integration patterns.

Webhook notifications

Risk signals created by any of the five detection paths can trigger real-time webhook notifications. Subscribe to risk.signal.created or risk.signal.escalated to react to new signals without polling. This covers signals from direct ingestion, event normalization, deepfake scans, ATO alerts, and velocity anomalies. See the webhooks guide for payload examples and integration patterns.

Usage metering

Anti-Fraud features are metered per billing cycle. Each detection path increments its own usage counter:

Metric	Metered action
`antifraud.risk_signals`	Risk signals ingested or generated (all five paths)
`antifraud.deepfake_scans`	Deepfake and impersonation scan requests
`antifraud.velocity_records`	Velocity scoring action records

Quotas vary by plan tier. You can check your current consumption with the usage API or in the console at Settings > Billing > Usage under the Anti-Fraud section. To verify whether a specific operation is allowed before performing it, use the limit check endpoint.

curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."

The response includes all Anti-Fraud counters with used, limit, and period fields so you can monitor consumption programmatically.

See the billing overview for the full list of 16 metered products and their default rates.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

Choosing an ingestion path

How it works

Prerequisites

Ingesting a signal

Required fields

Optional fields

Idempotency

Querying signals

List with filters

Get a single signal

Console view

Scoring guidelines

Event normalization

Built-in event mappings

Event fields

Tenant isolation

Deepfake and impersonation detection

Account takeover detection

Velocity and anomaly scoring

Webhook notifications

Usage metering

What’s next

​Choosing an ingestion path

​How it works

​Prerequisites

​Ingesting a signal

​Required fields

​Optional fields

​Idempotency

​Querying signals

​List with filters

​Get a single signal

​Console view

​Scoring guidelines

​Event normalization

​Built-in event mappings

​Event fields

​Tenant isolation

​Deepfake and impersonation detection

​Account takeover detection

​Velocity and anomaly scoring

​Webhook notifications

​Usage metering

​What’s next

Choosing an ingestion path

How it works

Prerequisites

Ingesting a signal

Required fields

Optional fields

Idempotency

Querying signals

List with filters

Get a single signal

Console view

Scoring guidelines

Event normalization

Built-in event mappings

Event fields

Tenant isolation

Deepfake and impersonation detection

Account takeover detection

Velocity and anomaly scoring

Webhook notifications

Usage metering

What’s next