Rules Execution Summary

Overview

The rulesExecutionSummary object is returned whenever the rules engine runs: on Create Transaction, Create Person, Create Company, Create Entity, Create Event, and in webhook payloads for Risk Analysis events. It summarizes which rules matched (hit), which did not (no hit), executed actions, and scoring metadata.

Where it appears

Context	Location
Create transaction (with `executeRules: true`)	Response root (`rulesExecutionSummary`)
Create person/company/entity (when risk matrix runs)	Response root and `rulesResult.rulesExecutionSummary`
Create event (when rules run)	Response root and `rulesResult.rulesExecutionSummary`
Risk analysis webhooks	`payload.rulesExecutionSummary`

Field reference

Field	Type	Description
rulesHit	`array`	Rules whose conditions were met. Each item includes `ruleId`, `ruleExternalId` (when configured), `riskMatrixId` / `riskMatrixName` when the rule belongs to a matrix (multi-matrix and audit-friendly), plus `name`, `description`, `score`, `priority`, `category`, `status`, `conditions`, and optionally `actions`.
rulesNoHit	`array`	Rules evaluated but conditions not met. Same structure as each rulesHit item.
actionsExecuted	`object`	Present only when at least one action ran. Aggregated actions from all rules that hit.
totalScore	`number`	Sum of the score of all rules that hit (excluding shadow rules).
scoreResult	`object`	Normalized score and label: `rawScore`, `normalizedScore`, and optional `label` (name, range, minScore, maxScore).
riskMatrixName	`string`	Name of the risk matrix that was executed.
executionTimeMs	`number`	Execution time of the rules engine in milliseconds.
trigger	`string`	Event that triggered the evaluation (e.g. `manual_evaluation`, `entity_created`, `enrichment_completed`, `created`).
matchedRulesCount	`number`	Number of rules that matched (same as `rulesHit.length`).
riskMatricesExecuted	`array`	Optional. One entry per risk matrix that contributed evaluated rules in this run: raw score, matched-rule count, and label metadata per matrix. Added when the API enriches the summary after evaluation (for example multi-matrix flows or persisted risk analysis). Omitted when not computed or empty.

rulesHit / rulesNoHit item

Field	Type	Description
ruleId	`string`	Rule UUID (persisted rule row).
ruleExternalId	`string \| null`	Business rule code when configured (e.g. `RG-ENTITY-1`).
riskMatrixId	`string \| null`	UUID of the risk matrix that owns this rule, or `null` if not tied to a matrix.
riskMatrixName	`string \| null`	Matrix display name when the execution context includes matrix labels.
name	`string`	Rule name.
description	`string`	Rule description.
score	`number \| null`	Rule score (points when it hits).
priority	`number \| null`	Rule priority.
category	`string`	Rule category.
status	`string`	Rule status (e.g. `active`, `shadow`).
conditions	`array`	Conditions evaluated: each `{ field, value, operator? }`.
actions	`object`	For rulesHit: executed actions. For rulesNoHit: configured actions. See below.

actions (inside each rule item)

Field	Type	Description
alerts	`array`	Alert definitions: `name`, `type`, `severity`, `description`.
suggestion	`string`	Suggestion type: `BLOCK`, `SUSPEND`, or `FLAG`.
status	`string`	Status set by the rule.
assignedUser	`object`	`{ userId: string }` if the rule assigns a user.
customKeys	`array`	Custom action keys (e.g. for workflows).

actionsExecuted (root)

Field	Type	Description
alerts	`array`	All alerts from rules that hit. Each alert can include `ruleId`, `ruleExternalId`, and `investigationId` (set after consolidation; null in the immediate response).
suggestion	`string`	Winning suggestion by weight: `BLOCK`, `SUSPEND`, or `FLAG`.
status	`string`	Final status applied (from the rule with highest weight).
assignedUser	`object`	`{ userId: string }` if any rule assigned a user.
customKeys	`array`	All custom action keys from rules that hit.

riskMatricesExecuted (each array item)

Field	Type	Description
riskMatrixId	`string \| null`	Matrix UUID, or `null` for rules not tied to a matrix row.
riskMatrixName	`string \| null`	Display name of the matrix (resolved from the run or from organization metadata).
rawScore	`number`	Sum of scores from rules that hit in this matrix (non-shadow hits), same basis as matrix-level breakdown in audits.
matchedRules	`number`	Count of rules that hit for this matrix in this execution.
labelName	`string \| null`	Risk label name applied to this matrix’s contribution (when label resolution ran).
labelColor	`string \| null`	Hex or token for UI when present.
labelSeverity	`string \| null`	Severity bucket: `low`, `medium`, `high`, or `critical`, when resolved.
matrixNormalizedScore	`number \| null`	Normalized 0–100 score for this matrix when available.

Complete example

The following example shows rulesExecutionSummary with every field populated as it would appear in an API response or webhook payload.

{
  "rulesHit": [
    {
      "ruleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ruleExternalId": "RG-ENTITY-1",
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Default Entity Matrix",
      "name": "High-risk country",
      "description": "Flags entities or transactions linked to high-risk jurisdictions.",
      "score": 30,
      "priority": 1,
      "category": "compliance",
      "status": "active",
      "conditions": [
        { "field": "entity.countryCode", "value": ["IR", "KP", "SY"], "operator": "in" },
        { "field": "entity.type", "value": "person" }
      ],
      "actions": {
        "alerts": [
          {
            "name": "High-risk country alert",
            "type": "create_alert",
            "severity": "high",
            "description": "Entity is linked to a high-risk jurisdiction."
          }
        ],
        "suggestion": "FLAG",
        "status": "PENDING_REVIEW"
      }
    }
  ],
  "rulesNoHit": [
    {
      "ruleId": "f6a7b8c9-d0e1-2345-f678-901234567890",
      "ruleExternalId": "RG-ENTITY-2",
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Default Entity Matrix",
      "name": "PEP match",
      "description": "Flags when PEP screening returns a match.",
      "score": 25,
      "priority": 2,
      "category": "compliance",
      "status": "active",
      "conditions": [
        { "field": "enrichment.complyadvantage_pep_enrichment.isPep", "value": true }
      ],
      "actions": {
        "alerts": [
          {
            "name": "PEP match",
            "type": "create_alert",
            "severity": "medium",
            "description": "PEP screening returned a match."
          }
        ],
        "suggestion": "SUSPEND"
      }
    }
  ],
  "actionsExecuted": {
    "alerts": [
      {
        "name": "High-risk country alert",
        "type": "create_alert",
        "severity": "high",
        "description": "Entity is linked to a high-risk jurisdiction.",
        "ruleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "ruleExternalId": "RG-ENTITY-1",
        "investigationId": null
      }
    ],
    "suggestion": "FLAG",
    "status": "PENDING_REVIEW",
    "customKeys": ["required_kyc"]
  },
  "totalScore": 30,
  "scoreResult": {
    "rawScore": 30,
    "normalizedScore": 42,
    "label": {
      "name": "Medium",
      "range": "30-80",
      "minScore": 30,
      "maxScore": 80
    }
  },
  "riskMatrixName": "Default Entity Matrix",
  "executionTimeMs": 156,
  "trigger": "entity_created",
  "matchedRulesCount": 1,
  "riskMatricesExecuted": [
    {
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Default Entity Matrix",
      "rawScore": 30,
      "matchedRules": 1,
      "labelName": "Medium",
      "labelColor": "#f5a623",
      "labelSeverity": "medium",
      "matrixNormalizedScore": 42
    }
  ]
}

Minimal example (no rules hit)

When no rules match, you still get rulesHit, rulesNoHit, totalScore, and metadata; actionsExecuted is omitted when empty.

{
  "rulesHit": [],
  "rulesNoHit": [
    {
      "ruleId": "f6a7b8c9-d0e1-2345-f678-901234567890",
      "ruleExternalId": "RG-ENTITY-2",
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Default Entity Matrix",
      "name": "PEP match",
      "description": "Flags when PEP screening returns a match.",
      "score": 25,
      "priority": 2,
      "category": "compliance",
      "status": "active",
      "conditions": [
        { "field": "enrichment.complyadvantage_pep_enrichment.isPep", "value": true }
      ],
      "actions": {
        "alerts": [
          {
            "name": "PEP match",
            "type": "create_alert",
            "severity": "medium",
            "description": "PEP screening returned a match."
          }
        ],
        "suggestion": "SUSPEND"
      }
    }
  ],
  "totalScore": 0,
  "scoreResult": {
    "rawScore": 0,
    "normalizedScore": 0,
    "label": {
      "name": "Low",
      "range": "0-30",
      "minScore": 0,
      "maxScore": 30
    }
  },
  "riskMatrixName": "Default Entity Matrix",
  "executionTimeMs": 98,
  "trigger": "manual_evaluation",
  "matchedRulesCount": 0
}

Notes

riskMatricesExecuted is not produced by the rules engine alone; the API merges it into rulesExecutionSummary when a per-matrix score breakdown exists. Single-matrix responses may only include riskMatrixName at the root without this array.
investigationId in actionsExecuted.alerts is assigned asynchronously after alert consolidation; it is null in the immediate API response.
scoreResult.normalizedScore is the 0–100 value persisted on the entity or audit; totalScore (and scoreResult.rawScore) is the raw sum of rule scores.
trigger values include: manual_evaluation, entity_created, enrichment_completed, check_completed, created, updated, and others depending on context.

Documentation Index

​Overview

​Where it appears

​Field reference

​rulesHit / rulesNoHit item

​actions (inside each rule item)

​actionsExecuted (root)

​riskMatricesExecuted (each array item)

​Complete example

​Minimal example (no rules hit)

​Notes