> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Ingest Risk Signal
> Ingest a raw risk signal event. Risk signals are the foundation of the Anti-Fraud Identity Firewall — they represent a single suspicious observation about a subject.
## Request
Origin of the signal. One of: `verification`, `login`, `attestation`, `external`, `manual`
Type of risk signal. One of: `velocity`, `geo_anomaly`, `device_fingerprint`, `behavior`, `deepfake`, `ato`, `impersonation`
Identifier of the entity being evaluated (user ID, issuer ID, attestation ID, IP address, etc.)
Type of the subject. One of: `user`, `issuer`, `attestation`, `session`, `ip`, `device`
Risk score from 0 (safe) to 100 (high risk). Scores ≥80 trigger automatic review decisions.
Arbitrary JSON payload with signal-specific context (device fingerprint, geo coordinates, behavior metrics, etc.)
Source IP address associated with this event.
User-Agent string associated with this event.
## Headers
UUID for idempotent signal ingestion. If omitted, a random key is generated. Duplicate signals with the same key are silently ignored.
## Response
UUID of the created risk signal.
The ingested risk score (0–100).
ISO 8601 timestamp of ingestion.
## OpenAPI
````yaml mint-openapi.yaml POST /v1/risk/signals
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/risk/signals:
post:
tags:
- Risk
summary: Ingest Risk Signal
description: >
Submit a risk signal for a specific entity. Risk signals are scored
observations
from fraud-detection sources such as device fingerprinting, IP
reputation services,
email verification providers, or your own internal rules engine.
Each signal is stored with full tenant isolation (row-level security)
and can be
used to inform downstream risk decisions.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- source
- signal_type
- score
- entity_type
- entity_id
properties:
source:
type: string
description: >-
Origin of the signal (e.g. device_fingerprint,
ip_reputation, email_verification, document_analysis,
behavioral)
example: device_fingerprint
signal_type:
type: string
description: Classification of the risk signal
example: velocity_anomaly
score:
type: number
format: float
minimum: 0
maximum: 1
description: Risk score between 0 (no risk) and 1 (highest risk)
example: 0.85
details:
type: object
additionalProperties: true
description: Arbitrary metadata to attach to the signal
example:
ip: 203.0.113.42
country: US
reason: multiple_accounts_same_device
entity_type:
type: string
description: The type of entity this signal relates to
enum:
- user
- device
- ip
- document
- session
example: user
entity_id:
type: string
description: Identifier of the entity being evaluated
example: usr_8f14e45f
responses:
'201':
description: Risk signal ingested
content:
application/json:
schema:
$ref: '#/components/schemas/RiskSignal'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
RiskSignal:
type: object
properties:
id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
source:
type: string
description: >-
Origin of the signal (e.g. device_fingerprint, ip_reputation,
email_verification, document_analysis, behavioral)
example: device_fingerprint
signal_type:
type: string
description: Classification of the risk signal
example: velocity_anomaly
score:
type: number
format: float
minimum: 0
maximum: 1
description: Risk score between 0 (no risk) and 1 (highest risk)
example: 0.85
details:
type: object
additionalProperties: true
description: Arbitrary metadata associated with the signal
example:
ip: 203.0.113.42
country: US
reason: multiple_accounts_same_device
entity_type:
type: string
description: The type of entity this signal relates to
enum:
- user
- device
- ip
- document
- session
example: user
entity_id:
type: string
description: Identifier of the entity being evaluated
example: usr_8f14e45f
created_at:
type: string
format: date-time
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````