Skip to main content
POST
Ingest Risk Signal
Submits a risk signal for a specific subject. Risk signals are scored observations from fraud-detection sources such as device fingerprinting, IP reputation services, email verification providers, or your own rules engine. Each signal is stored with full tenant isolation and can be used to inform downstream risk decisions. See the risk signals guide for integration details.

Signal sources

Signals must specify one of the following sources:

Subject types

Each signal must reference a subject. Supported types:

Risk score

The risk_score field is an integer between 0 and 100:
  • 0 — no risk detected
  • 50 — moderate risk
  • 80+ — triggers automatic review decisions
  • 100 — highest risk

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.

Authorizations

X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
signal_source
string
required
signal_type
string
required

Classification of the risk signal

Example:

"velocity_anomaly"

subject_id
string
required
subject_type
string
required
idempotency_key
string
ip_address
string
payload
any
risk_score
integer
user_agent
string

Response

Risk signal ingested

id
string<uuid>
tenant_id
string<uuid>
source
string

Origin of the signal (e.g. device_fingerprint, ip_reputation, email_verification, document_analysis, behavioral)

Example:

"device_fingerprint"

signal_type
string

Classification of the risk signal

Example:

"velocity_anomaly"

score
number<float>

Risk score between 0 (no risk) and 1 (highest risk)

Required range: 0 <= x <= 1
Example:

0.85

details
object

Arbitrary metadata associated with the signal

Example:
entity_type
enum<string>

The type of entity this signal relates to

Available options:
user,
device,
ip,
document,
session
Example:

"user"

entity_id
string

Identifier of the entity being evaluated

Example:

"usr_8f14e45f"

created_at
string<date-time>