---
title: "List categorization rules"
method: GET
path: "/books/rules"
tags: ["Books"]
---

# List categorization rules

`GET /books/rules`

## Request

- Base URL: `https://api.mercury.com/api/v1`
- URL: `https://api.mercury.com/api/v1/books/rules`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/mercurytechnologies/apis/mercury-api/docs/books/rules/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Query parameters

- `booksId` string, uuid: The Books instance to act on. Must be the token organization's own instance, which it defaults to.
- `pageToken` string: token for pagination
- `limit` integer: The maximum number of rules to return per page, from 1 to 100. Defaults to 50.

## Response `200`

- GetBooksAPICategorizationRulesResponse: A page of a Books instance's categorization rules, in priority order.
  - `nextPageToken` string, nullable: Pass as `pageToken` to fetch the next page, or null on the last page.
  - `rules` BooksAPICategorizationRule[], required: The rules on this page, highest priority first. When several rules match a transaction, the first one applies. Rules Books can't represent are omitted.
    - `conditions` BooksAPICategorizationRuleCondition[], required: The conditions a transaction must match. At least one; every condition must match (logical AND). There is no OR: an "any of" rule is written as separate rules.
      - union: A condition a transaction must match for a categorization rule to apply. `tag` says which condition it is (`amount`, `description`, `counterparty`, `debitCard`, `creditCard`, `user`, or `customCategory`) and `contents` holds its fields. A rule's conditions must all match; there is no OR, so an "any of" rule is written as separate rules.
        - object
          - `contents` BooksAPICategorizationRuleAmountCondition, 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.
            - `amount` number, double, required: The threshold, in dollars. Signed like the transaction amount: positive for money in, negative for money out.
            - `operator` 'lessThan' | 'lessThanOrEqualTo' | 'greaterThan' | 'greaterThanOrEqualTo' | 'equalTo', required: How to compare the transaction amount to `amount`.
          - `tag` 'amount', required
        - object
          - `contents` BooksAPICategorizationRuleDescriptionCondition, required: Matches transactions whose raw bank description contains a text, ignoring case (`tag`: `description`).
            - `contains` string, required: The text the bank description must contain, ignoring case.
          - `tag` 'description', required
        - object
          - `contents` BooksAPICategorizationRuleCounterpartyCondition, required: Matches transactions whose counterparty name is exactly a name (`tag`: `counterparty`). Only Mercury transactions carry a counterparty.
            - `name` string, required: The counterparty name the transaction must have, matched exactly.
          - `tag` 'counterparty', required
        - object
          - `contents` BooksAPICategorizationRuleDebitCardCondition, required: Matches transactions made with a Mercury debit card (`tag`: `debitCard`).
            - `debitCardId` string, uuid, required: The ID of the debit card.
          - `tag` 'debitCard', required
        - object
          - `contents` BooksAPICategorizationRuleCreditCardCondition, required: Matches transactions made with a Mercury credit card (`tag`: `creditCard`).
            - `creditCardId` string, uuid, required: The ID of the credit card.
          - `tag` 'creditCard', required
        - object
          - `contents` BooksAPICategorizationRuleUserCondition, required: Matches transactions made by a team member (`tag`: `user`).
            - `userId` string, uuid, required: The ID of the user who made the transaction.
          - `tag` 'user', required
        - object
          - `contents` BooksAPICategorizationRuleCustomCategoryCondition, required: Matches transactions whose current Mercury custom (expense) category is a category (`tag`: `customCategory`).
            - `customCategoryId` string, uuid, required: The ID of the custom category.
          - `tag` 'customCategory', required
    - `glCodeName` string, nullable: The display name of the general ledger (GL) account the rule categorizes to. Absent when the rule sets none.
    - `id` string, uuid, required: The rule's stable identifier.
    - `lastApplied` string, yyyy-mm-ddThh:MM:ssZ, nullable: The last time the rule matched a transaction. Absent if it never has.
    - `outputs` BooksAPICategorizationRuleOutput[], required: What the rule applies to a matching transaction. At least one.
      - `contents` BooksAPICategorizationRuleSetLedgerOutput, required: Sets the transaction's categorization to a ledger, i.e. a general ledger (GL) account (`tag`: `setLedger`).
        - `ledgerId` string, base58 (max length 22), required: The ID of the ledger matching transactions are categorized to.
      - `tag` 'setLedger', required
    - `status` 'active' | 'inactive' | 'invalid', required: Whether the rule currently categorizes transactions.

## Other responses

- `400`: Invalid `limit` or `pageToken` or `booksId`

## Changes

- **2026-11-03** `95c77a617769`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/books/rules/get.md)

---

[API](https://skmtc.dev/mercurytechnologies/apis/mercury-api.md) - [All operations](https://skmtc.dev/mercurytechnologies/apis/mercury-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mercurytechnologies/apis/mercury-api/revisions/95c77a617769?raw)