List categorization rules
Changed onReturns 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.
Request
- Base URLhttps://api.mercury.com/api/v1
- AuthHTTP bearer
- TypeScriptA function with typed inputs. Its response is checked against the schema.
Query parameters
The Books instance to act on. Must be the token organization's own instance, which it defaults to.
token for pagination
The maximum number of rules to return per page, from 1 to 100. Defaults to 50.
Response
Example response
{
"rules": [
{
"id": "00000000-0000-0000-0000-000000000000",
"lastApplied": "2016-07-22T00:00:00Z",
"outputs": [
{
"contents": {
"ledgerId": "7JRNsKwy2Lw66caxVU7WGC"
}
}
]
}
]
}Changes
- info
endpoint added
- info