List Violation Cases

Get violations grouped by account or entity with aggregated metrics

GET /api/violations/cases

cURL

curl -X GET "https://api.example.com/api/violations/cases?scan_id=abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "cases": [
    {
      "account_id": "ACC-2024-001",
      "violation_count": 3,
      "max_severity": "CRITICAL",
      "top_rule": "SAR_THRESHOLD",
      "total_amount": 45000,
      "violations": [
        {
          "id": "viol_789xyz",
          "rule_id": "SAR_THRESHOLD",
          "severity": "CRITICAL",
          "amount": 15000,
          "explanation": "Transaction exceeds SAR filing threshold",
          "status": "pending"
        },
        {
          "id": "viol_790abc",
          "rule_id": "VELOCITY_CHECK",
          "severity": "HIGH",
          "amount": 20000,
          "explanation": "Unusual transaction velocity detected",
          "status": "pending"
        },
        {
          "id": "viol_791def",
          "rule_id": "ROUND_AMOUNT",
          "severity": "MEDIUM",
          "amount": 10000,
          "explanation": "Suspicious round amount pattern",
          "status": "approved"
        }
      ]
    },
    {
      "account_id": "ACC-2024-002",
      "violation_count": 1,
      "max_severity": "HIGH",
      "top_rule": "CTR_MISSING",
      "total_amount": 12000,
      "violations": [
        {
          "id": "viol_792ghi",
          "rule_id": "CTR_MISSING",
          "severity": "HIGH",
          "amount": 12000,
          "explanation": "Currency transaction report not filed",
          "status": "pending"
        }
      ]
    }
  ],
  "total_cases": 2,
  "total_violations": 4,
  "compliance_score": 72.5
}

Retrieve violations organized by account/entity with summary statistics. Useful for identifying high-risk accounts with multiple violations.

Query Parameters

scan_id · string · required

Scan ID to retrieve cases for

severity · string

Filter cases to only include violations of this severity. Valid values: CRITICAL, HIGH, MEDIUM

Response

cases · array

Array of violation cases grouped by account

account_id · string

Account or entity identifier

violation_count · integer

Total number of violations for this account

max_severity · string

Highest severity level among all violations for this account

top_rule · string

Rule ID of the most severe violation

total_amount · number

Sum of all transaction amounts associated with violations

violations · array

List of violations for this account

id · string

Violation identifier

rule_id · string

Rule identifier

severity · string

Violation severity

amount · number

Transaction amount

explanation · string

Violation explanation

status · string

Review status: pending, approved, or false_positive

total_cases · integer

Number of accounts with active violations (excludes accounts with only false positives)

total_violations · integer

Total number of active violations (excludes false positives)

compliance_score · number

Compliance score for the scan (0-100)

cURL

curl -X GET "https://api.example.com/api/violations/cases?scan_id=abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "cases": [
    {
      "account_id": "ACC-2024-001",
      "violation_count": 3,
      "max_severity": "CRITICAL",
      "top_rule": "SAR_THRESHOLD",
      "total_amount": 45000,
      "violations": [
        {
          "id": "viol_789xyz",
          "rule_id": "SAR_THRESHOLD",
          "severity": "CRITICAL",
          "amount": 15000,
          "explanation": "Transaction exceeds SAR filing threshold",
          "status": "pending"
        },
        {
          "id": "viol_790abc",
          "rule_id": "VELOCITY_CHECK",
          "severity": "HIGH",
          "amount": 20000,
          "explanation": "Unusual transaction velocity detected",
          "status": "pending"
        },
        {
          "id": "viol_791def",
          "rule_id": "ROUND_AMOUNT",
          "severity": "MEDIUM",
          "amount": 10000,
          "explanation": "Suspicious round amount pattern",
          "status": "approved"
        }
      ]
    },
    {
      "account_id": "ACC-2024-002",
      "violation_count": 1,
      "max_severity": "HIGH",
      "top_rule": "CTR_MISSING",
      "total_amount": 12000,
      "violations": [
        {
          "id": "viol_792ghi",
          "rule_id": "CTR_MISSING",
          "severity": "HIGH",
          "amount": 12000,
          "explanation": "Currency transaction report not filed",
          "status": "pending"
        }
      ]
    }
  ],
  "total_cases": 2,
  "total_violations": 4,
  "compliance_score": 72.5
}

Use Cases

Identify high-risk accounts

Accounts with multiple CRITICAL violations or high total_amount may require investigation.

Filter by severity

GET /api/violations/cases?scan_id=abc123&severity=CRITICAL

Returns only cases containing CRITICAL violations.

Build compliance dashboards

Use total_cases and compliance_score to display scan-level metrics.

Severity Ranking

The max_severity is determined using this hierarchy:

1. CRITICAL (highest priority)
2. HIGH
3. MEDIUM (lowest priority)

The top_rule corresponds to the most severe violation for that account.

False Positive Handling

• cases array includes all accounts (even those with only false positives)
• total_cases excludes accounts with only false positives
• total_violations excludes false positive violations

This allows you to see the full picture while focusing metrics on active compliance issues.