Create a categorization rule

Creates a categorization rule in a Books instance: a rule that automatically categorizes imported transactions to a ledger, i.e. a general ledger (GL) account. The rule only applies to transactions categorized from now on; it does not re-categorize existing transactions. The body has conditions (1 to 10, all of which must match; logical AND, there is no OR) and outputs (at most one of each kind, so today exactly one setLedger), in the same shape getBooksCategorizationRules returns, so a listed rule's conditions and outputs can be sent back as is. Each condition has a tag and contents: amount (operator, one of lessThan, lessThanOrEqualTo, greaterThan, greaterThanOrEqualTo, or equalTo, and amount, a signed threshold in dollars: money in is positive and money out negative), description (contains), counterparty (name), debitCard (debitCardId), creditCard (creditCardId), user (userId), or customCategory (customCategoryId); every card, user, and custom category must belong to the organization. The only output is setLedger (ledgerId), a ledger the caller may edit (not read-only) in the Books instance; to find ledger IDs, use getBooksLedgers. There is no priority field: the new rule is placed among the existing rules by how specific its conditions are, and the first matching rule applies. Returns the created rule, in the shape getBooksCategorizationRules returns. A rule that doesn't validate, a ledger without a GL account, or conditions the organization already has a rule for are a 400 and create nothing; to see existing rules, use getBooksCategorizationRules.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
uuid

The Books instance to act on. Required for agent organization tokens; defaults to the token organization's instance.

Body Params

A categorization rule to create. There is no priority field: Books places the new rule among the existing ones by how specific its conditions are.

conditions
array of objects
required
length ≥ 1

The conditions a transaction must match, from 1 to 10. Every condition must match (logical AND); there is no OR, so an "any of" rule is written as separate rules. The organization may not already have a rule with the same conditions.

conditions*
contents
object
required

Matches transactions whose amount compares to a threshold (tag: amount). The amount is signed: money in (credits) is positive and money out (debits) is negative, and the threshold is compared against it as is, so lessThan -50 matches outflows of more than $50. A range is two amount conditions on the same rule.

string
enum
required
Allowed:
outputs
array of objects
required
length ≥ 1

What the rule applies to a matching transaction: at most one output of each kind, so today exactly one setLedger. Its ledger must be one the caller may edit in this Books instance.

outputs*

What a categorization rule does to a transaction it matches. tag says which output it is and contents holds its fields; today the only output is setLedger, which categorizes the transaction to the ledger contents.ledgerId.

contents
object
required

Sets the transaction's categorization to a ledger, i.e. a general ledger (GL) account (tag: setLedger).

string
enum
required
Allowed:
Responses

400

Invalid body or booksId

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json