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"
}

​
Request

​
signal_source
string
required
Origin of the signal. One of: verification, login, attestation, external, manual
​
signal_type
string
required
Type of risk signal. One of: velocity, geo_anomaly, device_fingerprint, behavior, deepfake, ato, impersonation
​
subject_id
string
required
Identifier of the entity being evaluated (user ID, issuer ID, attestation ID, IP address, etc.)
​
subject_type
string
required
Type of the subject. One of: user, issuer, attestation, session, ip, device
​
risk_score
integer
required
Risk score from 0 (safe) to 100 (high risk). Scores ≥80 trigger automatic review decisions.
​
payload
object
Arbitrary JSON payload with signal-specific context (device fingerprint, geo coordinates, behavior metrics, etc.)
​
ip_address
string
Source IP address associated with this event.
​
user_agent
string
User-Agent string associated with this event.

​
Headers

​
Idempotency-Key
string
UUID for idempotent signal ingestion. If omitted, a random key is generated. Duplicate signals with the same key are silently ignored.

​
Response

​
signal_id
string
UUID of the created risk signal.
​
risk_score
integer
The ingested risk score (0–100).
​
created_at
string
ISO 8601 timestamp of ingestion.

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>