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"
  }
}
'
import requests

url = "https://api.truthlocks.com/v1/risk/signals"

payload = {
    "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"
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://api.truthlocks.com/v1/risk/signals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.truthlocks.com/v1/risk/signals",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/risk/signals"

	payload := strings.NewReader("{\n  \"source\": \"device_fingerprint\",\n  \"signal_type\": \"velocity_anomaly\",\n  \"score\": 0.85,\n  \"entity_type\": \"user\",\n  \"entity_id\": \"usr_8f14e45f\",\n  \"details\": {\n    \"ip\": \"203.0.113.42\",\n    \"country\": \"US\",\n    \"reason\": \"multiple_accounts_same_device\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.truthlocks.com/v1/risk/signals")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source\": \"device_fingerprint\",\n  \"signal_type\": \"velocity_anomaly\",\n  \"score\": 0.85,\n  \"entity_type\": \"user\",\n  \"entity_id\": \"usr_8f14e45f\",\n  \"details\": {\n    \"ip\": \"203.0.113.42\",\n    \"country\": \"US\",\n    \"reason\": \"multiple_accounts_same_device\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.truthlocks.com/v1/risk/signals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source\": \"device_fingerprint\",\n  \"signal_type\": \"velocity_anomaly\",\n  \"score\": 0.85,\n  \"entity_type\": \"user\",\n  \"entity_id\": \"usr_8f14e45f\",\n  \"details\": {\n    \"ip\": \"203.0.113.42\",\n    \"country\": \"US\",\n    \"reason\": \"multiple_accounts_same_device\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "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"
}
{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}
{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}
{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

​
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>