Detection Rules

Overview

Custom rules allow your institution to define institution-specific detection logic beyond the 9 mandatory CBN rules. Rules are evaluated during transaction screening and can trigger REVIEW, ESCALATE, or BLOCK outcomes.

Common Workflows

New rule rollout: A compliance officer drafts a rule → Tests it against historical transactions → Activates it → Monitors false positive rate → Tunes thresholds. Emergency pause: A rule starts generating too many false positives during a holiday period → A BANK_ADMIN immediately pauses the rule → Investigates and updates thresholds → Re-activates.

Permissions

Action	Who Can Do It
Create, update rules	`BANK_ADMIN`, `COMPLIANCE_OFFICER`
Activate, pause, delete	`BANK_ADMIN`
View rules	All authenticated users

Rule Statuses

Status	Meaning
`DRAFT`	Created but not yet active
`ACTIVE`	Currently evaluating transactions
`PAUSED`	Temporarily disabled
`ARCHIVED`	Permanently retired

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/rules`	Create a custom rule
`GET`	`/api/v1/rules`	List all rules
`GET`	`/api/v1/rules/:id`	Retrieve rule details
`PATCH`	`/api/v1/rules/:id`	Update a rule
`PATCH`	`/api/v1/rules/:id/activate`	Activate a rule
`PATCH`	`/api/v1/rules/:id/pause`	Pause a rule
`DELETE`	`/api/v1/rules/:id`	Delete a custom rule

Note: CBN mandatory rules (ruleType: "CBN_BUILTIN") cannot be edited, paused, or deleted. They appear in listings for reference.

Create Rule

Define a new custom detection rule with conditions, logic, and actions. Request Body

Field	Type	Required	Description
`name`	`string`	✅	Human-readable rule name
`description`	`string`	✅	What the rule detects
`ruleType`	`string`	✅	Always `"CUSTOM"` for user-created rules
`configuration`	`object`	✅	Rule logic (see below)
`scoreModifier`	`number`	✅	Risk score to add (0–100)

Configuration Object

Field	Type	Required	Description
`conditions`	`array`	✅	List of condition objects
`conditionLogic`	`string`	✅	`"AND"` or `"OR"`
`outcome`	`string`	✅	`"REVIEW"`, `"ESCALATE"`, or `"BLOCK"`
`riskScore`	`number`	✅	Base risk score
`actions`	`string[]`		Array of actions like `["NOTIFY_OFFICER"]`

Condition Object

Field	Type	Description
`field`	`string`	`amount`, `channel`, `type`, `narration`, `senderName`, `receiverName`
`operator`	`string`	`GREATER_THAN`, `LESS_THAN`, `EQUALS`, `CONTAINS`, `REGEX_MATCH`
`value`	`any`	Value to compare against

Example Request

curl -X POST /v1/rules \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value ATM Withdrawal",
    "description": "Flag ATM withdrawals over ₦500,000",
    "ruleType": "CUSTOM",
    "configuration": {
      "conditions": [
        { "field": "amount", "operator": "GREATER_THAN", "value": 500000 },
        { "field": "channel", "operator": "EQUALS", "value": "ATM" }
      ],
      "conditionLogic": "AND",
      "outcome": "REVIEW",
      "riskScore": 45,
      "actions": ["NOTIFY_OFFICER"]
    },
    "scoreModifier": 45
  }'

const response = await fetch("/v1/rules", {
  method: "POST",
  headers: {
    Authorization: "Bearer <access_token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "High-Value ATM Withdrawal",
    description: "Flag ATM withdrawals over ₦500,000",
    ruleType: "CUSTOM",
    configuration: {
      conditions: [
        { field: "amount", operator: "GREATER_THAN", value: 500000 },
        { field: "channel", operator: "EQUALS", value: "ATM" },
      ],
      conditionLogic: "AND",
      outcome: "REVIEW",
      riskScore: 45,
      actions: ["NOTIFY_OFFICER"],
    },
    scoreModifier: 45,
  }),
});
const result = await response.json();

import requests

response = requests.post(
    "/v1/rules",
    headers={
        "Authorization": "Bearer <access_token>",
        "Content-Type": "application/json"
    },
    json={
        "name": "High-Value ATM Withdrawal",
        "description": "Flag ATM withdrawals over ₦500,000",
        "ruleType": "CUSTOM",
        "configuration": {
            "conditions": [
                {"field": "amount", "operator": "GREATER_THAN", "value": 500000},
                {"field": "channel", "operator": "EQUALS", "value": "ATM"}
            ],
            "conditionLogic": "AND",
            "outcome": "REVIEW",
            "riskScore": 45,
            "actions": ["NOTIFY_OFFICER"]
        },
        "scoreModifier": 45
    }
)
result = response.json()

Example Response -201 Created

{
  "success": true,
  "data": {
    "id": "rule_789xyz",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "name": "High-Value ATM Withdrawal",
    "description": "Flag ATM withdrawals over ₦500,000",
    "ruleType": "CUSTOM",
    "status": "DRAFT",
    "marbleScenarioId": null,
    "configuration": {
      "conditions": [
        { "field": "amount", "operator": "GREATER_THAN", "value": 500000 },
        { "field": "channel", "operator": "EQUALS", "value": "ATM" }
      ],
      "conditionLogic": "AND",
      "outcome": "REVIEW",
      "riskScore": 45,
      "actions": ["NOTIFY_OFFICER"]
    },
    "scoreModifier": 45,
    "version": 1,
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "activatedAt": null,
    "createdAt": "2026-05-16T10:00:00Z",
    "updatedAt": "2026-05-16T10:00:00Z"
  }
}

List Rules

Retrieve all rules including CBN built-ins and custom rules. Query Parameters

Parameter	Type	Default	Description
`status`	`string`	-	`DRAFT`, `ACTIVE`, `PAUSED`, `ARCHIVED`
`ruleType`	`string`	-	`CUSTOM`, `CBN_BUILTIN`
`page`	`integer`	`1`	Page number
`limit`	`integer`	`20`	Items per page

Example Request

curl -X GET "/v1/rules?status=ACTIVE&page=1&limit=20" \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "rule_789xyz",
        "name": "High-Value ATM Withdrawal",
        "ruleType": "CUSTOM",
        "status": "ACTIVE",
        "version": 1,
        "createdAt": "2026-05-16T10:00:00Z"
      },
      {
        "id": "CBN-001",
        "name": "Cash Threshold",
        "ruleType": "CBN_BUILTIN",
        "status": "ACTIVE",
        "version": 1,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 8,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Get Rule Detail

Retrieve the full configuration of a single rule. Path Parameters

Parameter	Type	Description
`id`	`string`	Rule UUID or CBN code

Example Request

curl -X GET /v1/rules/rule_789xyz \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "success": true,
  "data": {
    "id": "rule_789xyz",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "name": "High-Value ATM Withdrawal",
    "description": "Flag ATM withdrawals over ₦500,000",
    "ruleType": "CUSTOM",
    "status": "ACTIVE",
    "marbleScenarioId": null,
    "configuration": {
      "conditions": [
        { "field": "amount", "operator": "GREATER_THAN", "value": 500000 },
        { "field": "channel", "operator": "EQUALS", "value": "ATM" }
      ],
      "conditionLogic": "AND",
      "outcome": "REVIEW",
      "riskScore": 45,
      "actions": ["NOTIFY_OFFICER"]
    },
    "scoreModifier": 45,
    "version": 1,
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "activatedAt": "2026-05-16T11:00:00Z",
    "createdAt": "2026-05-16T10:00:00Z",
    "updatedAt": "2026-05-16T10:00:00Z"
  }
}

Update Rule

Modify an existing custom rule. CBN built-ins cannot be updated. Path Parameters

Parameter	Type	Description
`id`	`string`	Rule UUID

Request Body All fields optional. Same structure as Create Rule. Example Request

curl -X PATCH /v1/rules/rule_789xyz \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value ATM Withdrawal (Updated)",
    "configuration": {
      "conditions": [
        { "field": "amount", "operator": "GREATER_THAN", "value": 750000 }
      ],
      "conditionLogic": "AND",
      "outcome": "REVIEW",
      "riskScore": 50,
      "actions": ["NOTIFY_OFFICER"]
    },
    "scoreModifier": 50
  }'

Example Response -200 OK

{
  "success": true,
  "data": {
    "id": "rule_789xyz",
    "name": "High-Value ATM Withdrawal (Updated)",
    "configuration": {
      "conditions": [
        { "field": "amount", "operator": "GREATER_THAN", "value": 750000 }
      ],
      "conditionLogic": "AND",
      "outcome": "REVIEW",
      "riskScore": 50,
      "actions": ["NOTIFY_OFFICER"]
    },
    "scoreModifier": 50,
    "version": 2,
    "updatedAt": "2026-05-16T11:00:00Z"
  }
}

Updating an active rule does not automatically pause it. Consider pausing first if the change significantly alters detection logic.

Activate Rule

Enable a drafted or paused custom rule. Path Parameters

Parameter	Type	Description
`id`	`string`	Rule UUID

Example Request

curl -X PATCH /v1/rules/rule_789xyz/activate \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "success": true,
  "data": {
    "id": "rule_789xyz",
    "status": "ACTIVE",
    "activatedAt": "2026-05-16T12:00:00Z",
    "updatedAt": "2026-05-16T12:00:00Z"
  }
}

Pause Rule

Temporarily disable an active rule without deleting it. Path Parameters

Parameter	Type	Description
`id`	`string`	Rule UUID

Example Request

curl -X PATCH /v1/rules/rule_789xyz/pause \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "success": true,
  "data": {
    "id": "rule_789xyz",
    "status": "PAUSED",
    "updatedAt": "2026-05-16T12:05:00Z"
  }
}

Delete Rule

Permanently remove a custom rule. This action cannot be undone. Path Parameters

Parameter	Type	Description
`id`	`string`	Rule UUID

Example Request

curl -X DELETE /v1/rules/rule_789xyz \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "success": true,
  "data": {
    "id": "rule_789xyz",
    "deleted": true
  }
}

Deleting a rule removes it from all future screenings. Historical transactions screened by this rule retain their original verdicts.

Overview

Core Concepts

Features

Modules

API Reference

Detection Rules

Overview

Common Workflows

Permissions

Rule Statuses

Endpoints

Create Rule

List Rules

Get Rule Detail

Update Rule

Activate Rule

Pause Rule

Delete Rule

​Overview

​Common Workflows

​Permissions

​Rule Statuses

​Endpoints

​Create Rule

​List Rules

​Get Rule Detail

​Update Rule

​Activate Rule

​Pause Rule

​Delete Rule

Overview

Common Workflows

Permissions

Rule Statuses

Endpoints

Create Rule

List Rules

Get Rule Detail

Update Rule

Activate Rule

Pause Rule

Delete Rule