Skip to main content
POST
/
v1
/
risk
/
signals
Ingest Risk Signal
curl --request POST \
  --url https://api.truthlocks.com/v1/risk/signals \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "source": "device_fingerprint",
  "signal_type": "velocity_anomaly",
  "score": 0.85,
  "entity_type": "user",
  "entity_id": "usr_8f14e45f",
  "details": {
    "ip": "203.0.113.42",
    "country": "US",
    "reason": "multiple_accounts_same_device"
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "source": "device_fingerprint",
  "signal_type": "velocity_anomaly",
  "score": 0.85,
  "details": {
    "ip": "203.0.113.42",
    "country": "US",
    "reason": "multiple_accounts_same_device"
  },
  "entity_type": "user",
  "entity_id": "usr_8f14e45f",
  "created_at": "2023-11-07T05:31:56Z"
}
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:
SourceDescription
verificationSignals from the verification pipeline
loginLogin-related fraud indicators
attestationAttestation-related signals
externalSignals from third-party fraud providers
manualManually reviewed or submitted signals

​
Subject types

Each signal must reference a subject. Supported types:
Subject typeUse case
userSignals tied to a specific user account
issuerSignals related to an issuer entity
attestationSignals related to a specific attestation
sessionSession-level behavioral signals
ipIP-address-level signals
deviceSignals from device fingerprinting

​
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
​
source
string
required

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

Example:

"device_fingerprint"

​
signal_type
string
required

Classification of the risk signal

Example:

"velocity_anomaly"

​
score
number<float>
required

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

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

0.85

​
entity_type
enum<string>
required

The type of entity this signal relates to

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

"user"

​
entity_id
string
required

Identifier of the entity being evaluated

Example:

"usr_8f14e45f"

​
details
object

Arbitrary metadata to attach to the signal

Example:
{
  "ip": "203.0.113.42",
  "country": "US",
  "reason": "multiple_accounts_same_device"
}

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:
{
  "ip": "203.0.113.42",
  "country": "US",
  "reason": "multiple_accounts_same_device"
}
​
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>