Skip to main content
A ruleset is a named, reusable list of up to 50 rules; a sync has at most one ruleset attached. Each rule has conditions (groups of conditions: OR across groups, AND within a group) and one action. The Rules guide covers the behaviour; this page covers the API surface.
Fields:
  • Strings: merchantName, description, reference, accountName, merchantCategoryCode
  • Enums: direction, category, subcategory, customCategoryGroup, class, accountId, currency, dayOfWeek (monday…sunday)
  • Numbers: amount (absolute), signedAmount (keeps the sign), dayOfMonth (1–31)
category reads the resolved custom category when the user has one, else the raw bank category. dayOfMonth/dayOfWeek derive from the posting date in the account’s timezone. Operators:
  • Strings: contains, does_not_contain, equals, starts_with, ends_with, matches_glob / does_not_match_glob (* and ? wildcards, not regex), is_empty / is_not_empty (omit value), is_in, is_not_in
  • Enums: is, is_not, is_in, is_not_in
  • Numbers: gt, lt, eq, between
Actions: { "type": "skip" }, { "type": "email" } (notify by email, still written), { "type": "set_category", "value": "…" }, { "type": "set_category_group", "value": "…" }, { "type": "clear_category" }, { "type": "set_merchant", "value": "…" }, { "type": "set_description", "value": "…" }, { "type": "set_note", "value": "…" }, { "type": "add_tag", "value": "…" }. Merchant, description, note, and tag values support {merchant}, {description}, {category}, {subcategory}, {amount}, {account}, {reference}, and {date} placeholders. Rules evaluate in position order; the first matching rule wins each field, and the first skip stops evaluation. Notes and tags land in dedicated Note/Tags fields on Sheets, Notion, Airtable, and Webhook destinations (note / tags payload keys); the sync must have custom categories enabled, and YNAB is excluded. Category actions write the enriched custom_category / custom_category_group fields under the same gating. value is always a string, or an array of strings for between, is_in and is_not_in. A number is rejected with 400 parameter_invalid.
Rule amounts are the only place in v2 where money is not minor units. An amount value is a decimal string in major units — "100" means one hundred dollars, not one hundred cents — and it is compared against the absolute value of the transaction, so gt "100" matches a −104.96debitanda+104.96 debit and a +104.96 credit alike. Use a direction condition in the same group to restrict to one side. between takes two values and orders them for you.
Dry-run a ruleset before attaching it: POST /v2/rulesets/{id}/preview returns the actions each recent transaction would receive, and writes nothing.