Rule Object

A Rule defines automated categorization logic for transactions. When transactions are processed, rules are applied in priority order to automatically set category, entity, and other fields.

Object Structure

{
  "id": "rule123xyz",
  "name": "Categorize Salary",
  "description": "Auto-categorize monthly salary payments",
  "rationale": "Salary payments from employer always contain SALARY in the particulars",
  "priority": 10,
  "conditions": [
    {
      "field": "particulars",
      "operator": "contains",
      "value": "SALARY"
    }
  ],
  "actions": [
    {
      "field": "category",
      "value": "income"
    },
    {
      "field": "entity",
      "value": "Employer Inc"
    }
  ],
  "enabled": true,
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-15T10:30:00.000Z"
}

Fields

Core Fields

Field	Type	Required	Description
id	string	Auto	12-character unique identifier
name	string	Yes	Display name for the rule
description	string	No	Explanation of what the rule does
rationale	string	No	Why this rule exists (e.g., pattern observed, business logic)
priority	integer	No	Execution order (lower = first, default: 50)
enabled	boolean	No	Whether rule is active (default: true)
created_at	string	Auto	ISO 8601 timestamp of creation
updated_at	string	Auto	ISO 8601 timestamp of last update

Logic Fields

Field	Type	Description
conditions	array	Array of condition objects (see below)
actions	array	Array of action objects (see below)

Condition Object

Each condition specifies a field to match and how to match it.

{
  "field": "particulars",
  "operator": "contains",
  "value": "ATM"
}

Condition Fields

Field	Type	Required	Description
field	string	Yes	Transaction field to match
operator	string	Yes	Comparison operator
value	string	*	Value to compare against

*Value is required for all operators except is_null and is_not_null.

Matchable Fields

Field	Description
`particulars`	Transaction description
`entity`	Counterparty name
`category`	Current category
`inflow`	Credit amount
`outflow`	Debit amount
`balance`	Account balance
`type`	Transaction type
`po`	Purchase order
`comments`	User comments
`date`	Transaction date
`account`	Account ID

Operators

Operator	Description	Example
`equals`	Exact match (case-insensitive)	`{"field": "category", "operator": "equals", "value": "income"}`
`not_equals`	Does not match	`{"field": "type", "operator": "not_equals", "value": "unknown"}`
`contains`	Substring match	`{"field": "particulars", "operator": "contains", "value": "ATM"}`
`not_contains`	Does not contain	`{"field": "particulars", "operator": "not_contains", "value": "REVERSAL"}`
`starts_with`	Prefix match	`{"field": "particulars", "operator": "starts_with", "value": "NEFT"}`
`ends_with`	Suffix match	`{"field": "particulars", "operator": "ends_with", "value": "LTD"}`
`regex`	Regular expression	`{"field": "particulars", "operator": "regex", "value": "INV-\\d{4}"}`
`greater_than`	Numeric comparison	`{"field": "outflow", "operator": "greater_than", "value": 10000}`
`less_than`	Numeric comparison	`{"field": "inflow", "operator": "less_than", "value": 5000}`
`greater_than_or_equal`	Numeric comparison	`{"field": "outflow", "operator": "greater_than_or_equal", "value": 1000}`
`less_than_or_equal`	Numeric comparison	`{"field": "inflow", "operator": "less_than_or_equal", "value": 500}`
`is_null`	Field is empty	`{"field": "entity", "operator": "is_null"}`
`is_not_null`	Field has value	`{"field": "category", "operator": "is_not_null"}`

Action Object

Each action specifies what field to set when conditions match.

{
  "field": "category",
  "value": "utilities"
}

Action Fields

Field	Type	Required	Description
field	string	Yes	Transaction field to set
value	string	Yes	Value to set

Settable Fields

Field	Description	Example
`category`	Set transaction category	`{"field": "category", "value": "salary"}`
`entity`	Set transaction entity	`{"field": "entity", "value": "Amazon"}`
`type`	Set transaction type	`{"field": "type", "value": "expense"}`
`comments`	Add notes or tags	`{"field": "comments", "value": "bill-paid"}`

Priority

Rules are executed in priority order, lowest number first:

Priority 1-10: High priority rules
Priority 11-50: Normal rules (default is 50)
Priority 51-100: Low priority/fallback rules

When multiple rules match, they are all applied. If rules conflict (e.g., both try to set category), the higher priority (lower number) wins.

Multiple Conditions

When a rule has multiple conditions, ALL conditions must match for the rule to apply (AND logic).

{
  "conditions": [
    {"field": "particulars", "operator": "contains", "value": "AMAZON"},
    {"field": "outflow", "operator": "greater_than", "value": 500}
  ],
  "actions": [
    {"field": "category", "value": "shopping"},
    {"field": "entity", "value": "Amazon"}
  ]
}

This rule only matches Amazon purchases over 500.

Field Selection

When retrieving rules, use the fields parameter:

GET /api/v1/rules?fields=id,name,priority,enabled

Available fields: id, name, description, rationale, priority, conditions, actions, enabled, created_at, updated_at

Example: Utility Bill Rule

{
  "id": "rule001util",
  "name": "Utility Bills",
  "description": "Categorize electricity, water, and gas bills",
  "rationale": "All utility providers in Karnataka include their name in the transaction particulars",
  "priority": 20,
  "conditions": [
    {
      "field": "particulars",
      "operator": "regex",
      "value": "(ELECTRICITY|WATER|GAS|BESCOM|BWSSB)"
    }
  ],
  "actions": [
    {
      "field": "category",
      "value": "utilities"
    }
  ],
  "enabled": true,
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-01T00:00:00.000Z"
}

Example: Salary Rule

{
  "id": "rule002sal",
  "name": "Monthly Salary",
  "description": "Categorize salary credits from employer",
  "rationale": "All salary credits contain SALARY in particulars and are above 50k",
  "priority": 5,
  "conditions": [
    {
      "field": "particulars",
      "operator": "contains",
      "value": "SALARY"
    },
    {
      "field": "inflow",
      "operator": "greater_than",
      "value": 50000
    }
  ],
  "actions": [
    {
      "field": "category",
      "value": "income"
    },
    {
      "field": "entity",
      "value": "Acme Corp"
    },
    {
      "field": "type",
      "value": "income"
    }
  ],
  "enabled": true,
  "created_at": "2024-06-01T00:00:00.000Z",
  "updated_at": "2024-06-01T00:00:00.000Z"
}

Rules API - Overview and all endpoints
Create Rule - Create endpoint
Transaction Object - Transaction reference
Transactions Search - Search using rule conditions