Create categorisation rule

POST https://app.speybooks.com/api/v1/categorisation-rules/

Creates a new categorisation rule. If a rule with the same field, operator, and value already exists, the target account is updated (upsert semantics) rather than creating a duplicate.

Description values are normalised before storage: converted to uppercase, common bank prefixes stripped, trailing digits removed. This improves matching against varying bank formats.

Each organisation is limited to 100 rules. Creating a rule emits a categorisation signal to the global rules aggregation pipeline (TMADD 2.0).

Body parameters

field string required
Transaction field to match against (description, contact_name, amount, reference, or metadata.* fields).
descriptioncontact_nameamountreferencemetadata.categorymetadata.projectmetadata.departmentmetadata.tag
name string required
Rule display name (1-100 characters).
operator string required
Match operator (contains, equals, starts_with, ends_with, greater_than, less_than, regex).
containsequalsstarts_withends_withgreater_thanless_thanregex
targetAccountId string required
Target account ID (e.g. acc_4000). The account transactions will be categorised to when this rule matches.
value string required
Value to match (1-500 characters). Description values are auto-normalised. Regex patterns are validated.
active boolean optional
Whether the rule is active. Default true.
description string optional
Optional rule description (max 500 characters).
priority integer optional
Rule priority (0-999). Higher priority rules are evaluated first. Default 0.

Response

201 Rule created (or upserted if same field+operator+value exists). Returns rule details with resolved account.
Show response fields
active boolean
field string
id integer
name string
operator string
priority integer
targetAccountCode string
targetAccountId string
targetAccountName string
value string

Error codes

400 Validation error: invalid regex, invalid account ID, or organisation rule limit reached (100).
404 Target account not found.