Rules API - Firefly III

Overview

The Rules API allows you to create automation rules that process transactions based on triggers and actions. Rules can automatically categorize transactions, set budgets, update descriptions, and perform many other actions based on conditions you define.

List All Rules

curl -X GET "https://demo.firefly-iii.org/api/v1/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/rules

Query Parameters

page

integer

Page number for pagination

Response Fields

string

Rule ID

created_at

string

ISO 8601 timestamp of creation

updated_at

string

ISO 8601 timestamp of last update

rule_group_id

string

Rule group ID

rule_group_title

string

Rule group title

title

string

Rule title

description

string

Rule description

order

integer

Execution order within group

active

boolean

Whether the rule is active

strict

boolean

If true, all triggers must match (AND). If false, any trigger can match (OR)

stop_processing

boolean

Stop processing other rules after this one executes

trigger

string

When to trigger: store-journal, update-journal, or manual-activation

triggers

array

Array of trigger conditions

actions

array

Array of actions to perform

Trigger Object

triggers[].id

string

Trigger ID

triggers[].type

string

Trigger type (e.g., description_contains, amount_more, source_account_is)

triggers[].value

string

Trigger value to match against

triggers[].prohibited

boolean

If true, inverts the trigger (NOT condition)

triggers[].order

integer

Trigger order

triggers[].active

boolean

Whether this trigger is active

triggers[].stop_processing

boolean

Stop processing other triggers after this one

Action Object

actions[].id

string

Action ID

actions[].type

string

Action type (e.g., set_category, set_budget, add_tag)

actions[].value

string

Action value/parameter

actions[].order

integer

Action execution order

actions[].active

boolean

Whether this action is active

actions[].stop_processing

boolean

Stop processing other actions after this one

Create Rule

curl -X POST "https://demo.firefly-iii.org/api/v1/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Categorize Amazon Purchases",
    "description": "Auto-categorize Amazon transactions",
    "rule_group_id": "1",
    "trigger": "store-journal",
    "strict": false,
    "active": true,
    "stop_processing": false,
    "triggers": [
      {
        "type": "description_contains",
        "value": "AMAZON",
        "prohibited": false,
        "active": true
      }
    ],
    "actions": [
      {
        "type": "set_category",
        "value": "Shopping",
        "active": true
      },
      {
        "type": "add_tag",
        "value": "online-purchase",
        "active": true
      }
    ]
  }'

Endpoint: POST /v1/rules

Request Body

title

string

required

Rule title (1-100 characters, must be unique)

description

string

Rule description (1-32,768 characters)

rule_group_id

integer

Rule group ID (required without rule_group_title)

rule_group_title

string

Rule group title (1-255 characters, required without rule_group_id)

trigger

string

required

When to trigger: store-journal, update-journal, or manual-activation

strict

boolean

default:"false"

If true, ALL triggers must match (AND logic). If false, ANY trigger matching executes the rule (OR logic)

stop_processing

boolean

default:"false"

Stop processing remaining rules after this one executes

active

boolean

default:"true"

Whether the rule is active

triggers

array

required

Array of trigger objects (minimum 1, at least 1 must be active)

actions

array

required

Array of action objects (minimum 1, at least 1 must be active)

Trigger Object Fields

triggers[].type

string

required

Trigger type (see Trigger Types below)

triggers[].value

string

Value to match (required for most trigger types, max 1024 characters)

triggers[].prohibited

boolean

default:"false"

Invert the trigger (NOT condition)

triggers[].active

boolean

default:"true"

Whether this trigger is active

triggers[].stop_processing

boolean

default:"false"

Stop processing other triggers after this one

Action Object Fields

actions[].type

string

required

Action type (see Action Types below)

actions[].value

string

Action value/parameter (required for most action types)

actions[].active

boolean

default:"true"

Whether this action is active

actions[].stop_processing

boolean

default:"false"

Stop processing other actions after this one

Common Trigger Types

Transaction Properties

description_contains - Description contains text
description_starts - Description starts with text
description_ends - Description ends with text
description_is - Description exactly matches
amount_less - Amount less than value
amount_more - Amount more than value
amount_exactly - Amount exactly equals
date_is - Date is specific date
date_before - Date before specific date
date_after - Date after specific date

Account Triggers

source_account_starts - Source account name starts with
source_account_ends - Source account name ends with
source_account_contains - Source account name contains
source_account_is - Source account exactly matches
destination_account_starts - Destination account starts with
destination_account_ends - Destination account ends with
destination_account_contains - Destination account contains
destination_account_is - Destination exactly matches

Other Conditions

transaction_type - Transaction type is (withdrawal/deposit/transfer)
category_is - Category is specific category
budget_is - Budget is specific budget
tag_is - Has specific tag
notes_contain - Notes contain text
no_category - Has no category
no_budget - Has no budget
no_tag - Has no tags
has_attachments - Has attachments
has_no_attachments - Has no attachments

Common Action Types

Set Properties

set_category - Set category by name
set_budget - Set budget by name
clear_category - Remove category
clear_budget - Remove budget
add_tag - Add tag
remove_tag - Remove tag
remove_all_tags - Remove all tags
set_description - Set description
append_description - Append to description
prepend_description - Prepend to description

Account Actions

set_source_account - Change source account
set_destination_account - Change destination account

Other Actions

set_notes - Set notes
append_notes - Append to notes
clear_notes - Remove notes
link_to_bill - Link to bill
convert_withdrawal - Convert to withdrawal
convert_deposit - Convert to deposit
convert_transfer - Convert to transfer

Trigger Timing:

store-journal: Runs when a new transaction is created
update-journal: Runs when a transaction is updated
manual-activation: Only runs when manually triggered

Get Rule by ID

curl -X GET "https://demo.firefly-iii.org/api/v1/rules/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/rules/{id} Returns the same response fields as the List endpoint.

Update Rule

curl -X PUT "https://demo.firefly-iii.org/api/v1/rules/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Amazon Rule",
    "active": true,
    "triggers": [
      {
        "type": "description_contains",
        "value": "AMAZON"
      },
      {
        "type": "description_contains",
        "value": "AMZ"
      }
    ]
  }'

Endpoint: PUT /v1/rules/{id} Accepts the same parameters as Create Rule. All fields are optional.

Delete Rule

curl -X DELETE "https://demo.firefly-iii.org/api/v1/rules/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: DELETE /v1/rules/{id} Deletes the rule. Does not affect transactions that were already processed.

Test Rule

curl -X GET "https://demo.firefly-iii.org/api/v1/rules/{id}/test" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/rules/{id}/test Tests the rule against existing transactions to see which ones would be affected.

Query Parameters

start

string

Start date for test range (YYYY-MM-DD)

end

string

End date for test range (YYYY-MM-DD)

Trigger Rule

curl -X POST "https://demo.firefly-iii.org/api/v1/rules/{id}/trigger" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  }'

Endpoint: POST /v1/rules/{id}/trigger Manually executes the rule on existing transactions within the specified date range.

Request Body

start_date

string

Start date (YYYY-MM-DD)

end_date

string

End date (YYYY-MM-DD)

accounts

array

Array of account IDs to limit processing to

Validate Expression

curl -X GET "https://demo.firefly-iii.org/api/v1/rules/validate-expression?expression=AMAZON" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/rules/validate-expression Validates a rule expression before creating a rule.

Query Parameters

expression

string

required

Expression to validate

Best Practices

Rule Organization

Use rule groups: Organize related rules into groups
Order matters: Rules execute in order; place most important rules first
Use stop_processing: Prevent unnecessary rule execution after a match
Test before activating: Use the test endpoint to verify rule behavior

Efficient Trigger Design

Be specific: Use exact matches when possible (description_is vs description_contains)
Combine triggers: Use multiple triggers with strict=true for precise matching
Use prohibited wisely: NOT conditions can slow down processing
Deactivate unused triggers: Keep rules lean by removing inactive triggers

Action Best Practices

One action per purpose: Don’t overcomplicate with too many actions
Order actions logically: Some actions depend on others
Avoid conflicts: Don’t create rules that contradict each other
Use clear values: Make action values descriptive and consistent

Example: Multi-Condition Rule

{
  "title": "Business Expenses",
  "strict": true,
  "triggers": [
    {
      "type": "amount_more",
      "value": "50.00"
    },
    {
      "type": "description_contains",
      "value": "business"
    },
    {
      "type": "no_category",
      "value": "true"
    }
  ],
  "actions": [
    {
      "type": "set_category",
      "value": "Business Expense"
    },
    {
      "type": "add_tag",
      "value": "tax-deductible"
    },
    {
      "type": "append_notes",
      "value": "Auto-categorized by rule"
    }
  ]
}

This rule:

Only processes transactions over $50
That contain “business” in the description
That don’t already have a category
Then sets category, adds tag, and appends a note

​Overview

​List All Rules

​Query Parameters

​Response Fields

​Trigger Object

​Action Object

​Create Rule

​Request Body

​Trigger Object Fields

​Action Object Fields

​Common Trigger Types

​Transaction Properties

​Account Triggers

​Other Conditions

​Common Action Types

​Set Properties

​Account Actions

​Other Actions

​Get Rule by ID

​Update Rule

​Delete Rule

​Test Rule

​Query Parameters

​Trigger Rule

​Request Body

​Validate Expression

​Query Parameters

​Best Practices

​Rule Organization

​Efficient Trigger Design

​Action Best Practices

​Example: Multi-Condition Rule

Overview

List All Rules

Query Parameters

Response Fields

Trigger Object

Action Object

Create Rule

Request Body

Trigger Object Fields

Action Object Fields

Common Trigger Types

Transaction Properties

Account Triggers

Other Conditions

Common Action Types

Set Properties

Account Actions

Other Actions

Get Rule by ID

Update Rule

Delete Rule

Test Rule

Query Parameters

Trigger Rule

Request Body

Validate Expression

Query Parameters

Best Practices

Rule Organization

Efficient Trigger Design

Action Best Practices

Example: Multi-Condition Rule