Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.verilock.io/llms.txt

Use this file to discover all available pages before exploring further.

The Risk Score Engine produces a unified 0 — 100 composite score for each verification session by combining six weighted signal components. Use it to automate approval workflows and flag high-risk sessions for manual review.

​
Risk Levels

Score RangeLevelSuggested Action
0 — 25LowAuto-approve
26 — 50MediumApprove with monitoring
51 — 75HighManual review recommended
76 — 100CriticalBlock or escalate

​
Score Components

The composite score is a weighted sum of six individual component scores:
ComponentWeightDescription
Document authenticity25%MRZ validation, tamper detection, document expiry, hologram analysis
Face match20%Similarity between selfie and document photo
Liveness15%Passive or active liveness detection score
AML screening15%Sanctions, PEP, and adverse media screening results
Device fingerprint15%Browser/device anomalies, VPN, bot detection
Data consistency10%Cross-field validation (name/DOB/address consistency across sources)
Component weights are defaults. Custom weights can be configured per workflow in Dashboard > Workflows > Risk Settings.

​
API

​
Get Risk Score

GET /v1/sessions/{id}/risk
Returns the full risk breakdown for a completed session. 
curl -X GET \
  "https://verilock.io/api/v1/sessions/ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890/risk" \
  -H "Authorization: Bearer qi_live_your_api_key_here"

{
  "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "composite_score": 12,
  "risk_level": "low",
  "components": {
    "document_authenticity": {
      "score": 8,
      "weight": 0.25,
      "weighted_score": 2.0,
      "details": {
        "mrz_valid": true,
        "tamper_detected": false,
        "document_expired": false
      }
    },
    "face_match": {
      "score": 5,
      "weight": 0.20,
      "weighted_score": 1.0,
      "details": {
        "similarity": 96.4
      }
    },
    "liveness": {
      "score": 10,
      "weight": 0.15,
      "weighted_score": 1.5,
      "details": {
        "liveness_score": 92.5,
        "liveness_mode": "active"
      }
    },
    "aml_screening": {
      "score": 0,
      "weight": 0.15,
      "weighted_score": 0.0,
      "details": {
        "matches_found": 0
      }
    },
    "device_fingerprint": {
      "score": 15,
      "weight": 0.15,
      "weighted_score": 2.25,
      "details": {
        "device_risk_score": 15,
        "fraud_signals": []
      }
    },
    "data_consistency": {
      "score": 10,
      "weight": 0.10,
      "weighted_score": 1.0,
      "details": {
        "name_match": true,
        "dob_match": true
      }
    }
  },
  "calculated_at": "2026-03-18T10:30:00Z"
}

​
Response Fields

FieldTypeDescription
session_idstringThe session ID
composite_scoreintegerUnified risk score (0-100)
risk_levelstringlow, medium, high, or critical
componentsobjectBreakdown of each scoring component
components.*.scoreintegerRaw component score (0-100)
components.*.weightnumberWeight applied to this component
components.*.weighted_scorenumberScore multiplied by weight
components.*.detailsobjectComponent-specific details
calculated_atstringISO 8601 timestamp

​
Using Risk Scores in Workflows

You can configure automatic actions based on risk levels in Dashboard > Workflows > Risk Rules:
RuleConditionAction
Auto-approvecomposite_score <= 25Approve session automatically
Flag for reviewcomposite_score > 50Assign to review queue
Blockcomposite_score > 75Decline session automatically
Combine risk scoring with webhooks to build fully automated verification pipelines. Subscribe to session.completed and check the risk_score field in the payload.