Books

List categorization rules

Changed on

Returns the categorization rules of a Books instance that Books can represent (see the end of this description for which are omitted), highest priority first: the rules that automatically categorize imported transactions to ledgers, i.e. general ledger (GL) accounts. When several rules match a transaction, the first one in this order applies. Rules are returned a page at a time, 50 by default and up to 100 with limit: when the response has a nextPageToken, pass it as pageToken to get the next page. A page token is a position in the priority order, so a rule added, deleted, or reordered between page requests can shift which rules the remaining pages hold: a rule moved across the position can be listed twice or not at all. Rules can also occasionally be renumbered while you page; if that happens, a page may skip or repeat rules, so restart from the first page if you need an exact snapshot. Each rule has: id; conditions, the conditions a transaction must match, at least one, all of which must match (logical AND; there is no OR, so an "any of" rule is written as separate rules); outputs, what the rule does to a matching transaction; status: active (it categorizes matching transactions), inactive (disabled), or invalid (no longer valid, so it categorizes nothing); glCodeName, the display name of the GL account it categorizes to; and lastApplied, the last time it matched a transaction. Each condition is an object whose tag says what it tests and whose contents holds its fields: amount (operator, one of lessThan, lessThanOrEqualTo, greaterThan, greaterThanOrEqualTo, or equalTo, and amount, a threshold in dollars), description (contains: the raw bank description contains this text, ignoring case), counterparty (name: the counterparty name is exactly this), debitCard (debitCardId), creditCard (creditCardId), user (userId: the team member who made the transaction), or customCategory (customCategoryId: the transaction's Mercury custom category). Amounts are signed: money in (credits) is positive and money out (debits) is negative, and the threshold is compared against the signed amount as is, so lessThan -50 matches outflows of more than $50. Each output has a tag and contents the same way; the only one today is setLedger, whose ledgerId is the ledger matching transactions are categorized to (look it up with getBooksLedgers). Rules Books can't represent are omitted: rules with a condition or output outside this vocabulary, such as accounting-integration rules that set a Mercury custom category, and rules whose GL account no longer maps to a Books ledger. So this list can be shorter than the organization's full rule list, and an omitted rule can still take precedence over a listed one.

get/books/rules

Request

Query parameters

booksIdstring uuid

The Books instance to act on. Must be the token organization's own instance, which it defaults to.

pageTokenstring

token for pagination

limitinteger

The maximum number of rules to return per page, from 1 to 100. Defaults to 50.

Response

nextPageTokenstring nullable

Pass as pageToken to fetch the next page, or null on the last page.

Example response

{
  "rules": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "lastApplied": "2016-07-22T00:00:00Z",
      "outputs": [
        {
          "contents": {
            "ledgerId": "7JRNsKwy2Lw66caxVU7WGC"
          }
        }
      ]
    }
  ]
}

Changes