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

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


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](/guides/risk-signals) for integration details.

### Signal sources

Signals must specify one of the following sources:

| Source         | Description                              |
| :------------- | :--------------------------------------- |
| `verification` | Signals from the verification pipeline   |
| `login`        | Login-related fraud indicators           |
| `attestation`  | Attestation-related signals              |
| `external`     | Signals from third-party fraud providers |
| `manual`       | Manually reviewed or submitted signals   |

### Subject types

Each signal must reference a subject. Supported types:

| Subject type  | Use case                                  |
| :------------ | :---------------------------------------- |
| `user`        | Signals tied to a specific user account   |
| `issuer`      | Signals related to an issuer entity       |
| `attestation` | Signals related to a specific attestation |
| `session`     | Session-level behavioral signals          |
| `ip`          | IP-address-level signals                  |
| `device`      | Signals 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.


## 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 <jwt>` 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

````