Categorizing Transactions - Asset API Documentation

Overview

Categorization assigns Transactions to the correct Ledger(s) in the Chart of Accounts, ensuring accurate financial reporting and compliance. Accurate categorization is not just good bookkeeping—it’s a legal and financial necessity. Misclassified expenses can lead to tax complications, compliance issues, and financial misreporting. Yet, manual categorization is consistently reported as one of the most tedious responsibilities for Business owners. At Asset, we’ve built a best-in-class categorization system that reduces the time and effort required to categorize Transactions, ensuring accuracy while allowing Business Owners to focus on running their companies.

How Categorization Works in Asset

Categorization happens directly on the Transaction. Each Transaction carries a review status and a set of line items that record how the Transaction is categorized, and each line item assigns an amount to a Ledger (its category). A Transaction with a single line item is categorized to one Ledger; a Transaction with several line items is split across multiple categories, with the line item amounts always summing to the Transaction amount. Each Transaction that enters Asset follows a structured categorization pipeline to determine those line items:

Transaction Enters Asset
- When a new Transaction enters Asset, it starts out uncategorized: it has no line items and its posted flag is false.
Categorization Pipeline The Transaction moves through a multi-step process to determine the appropriate category:
- Transfers Detection - Was the Transaction a transfer between accounts?
- Similarity-Based Categorization - Have we previously categorized a similar Transaction?
- AI-Powered Categorization - What does AI predict the Transaction should be?
- Uncategorized Transactions - If no match is found, the customer provides the correct category.
Business Review and Finalization
- Once the Categorization Pipeline assigns line items, the Transaction is categorized and its posted flag is set to true, and it is ready for Business review.
- Asset recommends that Tenants include a workflow step requiring Businesses to review and confirm assigned categories, ensuring accuracy.
- Any Uncategorized Transactions should be manually assigned to complete the books for the period.

Categorization Attributes in Asset

To support customizable workflows, Asset exposes the following categorization attributes on each Transaction:

Attribute	Description
Posted	Whether the Transaction is posted to the books: `false` while it is uncategorized, and `true` once it has been categorized.
Status	The categorization review status of the Transaction, derived from its journal entry: `bookkeeper_pending`, `business_pending`, or `confirmed`. A Transaction is finalized once its status is `confirmed`. Null when the Transaction has no status.
Line Items	The categorized allocations of the Transaction. Each line item carries the `ledger_id` (and `category` name) it is categorized to and the `amount` allocated to it, signed in the same direction as the Transaction amount. Null when the Transaction has no categorization.

These attributes allow Tenants to build workflows that ensure Transactions are properly categorized while maintaining flexibility based on Business needs.

How to Categorize a Transaction in Asset

To categorize or re-categorize a Transaction, call the Update Transactions for a Business endpoint. The endpoint accepts an array, so one or more Transactions can be updated in a single request.

PATCH /v0/business/{business_id}/transactions

Path Parameters:

Business ID – Specifies the Business where the Transactions are being updated.

Request Body – an array of update items, each with:

Transaction ID (required) – Identifies the specific Transaction to update.
Type (optional) – The updated type of the Transaction (business or personal).
Tags (optional) – Inline tag input to merge into the Transaction’s tags.
Line Items (optional) – Replaces the Transaction’s line items with a new set of categorized allocations. Each line item has:
- Ledger ID – The Ledger (category) to allocate the amount to.
- Description – The description of the line item.
- Amount – The amount allocated to the line item, signed in the same direction as the Transaction amount. Provide a single line item to change the category, or several to split the Transaction across categories; the amounts must sum to the Transaction amount.

Re-categorize to a single category (a $89.23 outflow assigned entirely to Office Supplies):

[
  {
    "transaction_id": "txn_WQMDNUHpBThYSNh4AprDBo",
    "line_items": [
      {
        "ledger_id": "ldg_Ns6rRRLYVZPh4cVB7MDby5",
        "description": "Office Supplies",
        "amount": -89.23
      }
    ]
  }
]

Split across multiple categories (a $100 outflow split evenly between Office Supplies and Travel):

[
  {
    "transaction_id": "txn_WQMDNUHpBThYSNh4AprDBo",
    "line_items": [
      {
        "ledger_id": "ldg_Ns6rRRLYVZPh4cVB7MDby5",
        "description": "Office Supplies",
        "amount": -50.00
      },
      {
        "ledger_id": "ldg_WQMDNUHpBThYSNh4AprDBo",
        "description": "Travel",
        "amount": -50.00
      }
    ]
  }
]

Categorizing a Transaction—assigning its line items—is what confirms it: its status moves to confirmed and it is finalized on the books. Once updated, the new categorization will reflect in the application. A typical Tenant workflow is to List Transactions for a Business (optionally filtering to unconfirmed Transactions), review each Transaction’s line items, and call the update endpoint to set the correct Ledger on the line items, confirming the Transaction.

Categorizing High-Impact Transactions First

Not all Transactions carry the same weight. To help Businesses clear the most outstanding value with the least effort, Asset groups similar unconfirmed Transactions and ranks those groups by impact—the share of outstanding dollar value each group represents. Categorizing a high-impact group at once clears more of the books in a single step. To fetch these groups, call the List high-impact Transaction groups to categorize endpoint:

GET /v0/business/{business_id}/categorization

Query Parameters:

limit (optional) – Maximum number of Transaction groups to return (1–50, default 10).
account_ids (optional) – Restrict to these External Account IDs, comma-separated.

Each group in the response contains:

Field	Description
transaction_ids	The IDs of the unconfirmed Transactions in this group. Applying a category to all of them clears the whole group.
transaction_count	The number of Transactions in the group.
total_amount	The total dollar value of the Transactions in the group, summed as absolute amounts.
impact	The share of outstanding dollar value this group represents (`total_amount` divided by the total dollar value of all unconfirmed Transactions). Higher means categorizing this group clears more outstanding value.

Example response:

{
  "data": [
    {
      "transaction_ids": [
        "txn_WQMDNUHpBThYSNh4AprDBo",
        "txn_2xPbN4qFxA97NZHtxeLPUy"
      ],
      "transaction_count": 12,
      "total_amount": 1480.32,
      "impact": 0.18
    }
  ]
}

A recommended bulk-categorization workflow:

Fetch the high-impact groups from GET /v0/business/{business_id}/categorization.
Fetch the Transactions in a group (using the returned transaction_ids) so the Business can confirm they belong together.
Update them all at once by passing every Transaction in the group to PATCH /v0/business/{business_id}/transactions with the chosen line items, categorizing the entire group in a single request.

Questions? Reach out via our Contact form.

​Overview

​How Categorization Works in Asset

​Categorization Attributes in Asset

​How to Categorize a Transaction in Asset

​Categorizing High-Impact Transactions First

Overview

How Categorization Works in Asset

Categorization Attributes in Asset

How to Categorize a Transaction in Asset

Categorizing High-Impact Transactions First