Configure chart of accounts and keyword triggers

Who does this: Bookkeeper · Senior Accountant · Platform Admin When: Onboarding a new bookkeeping client, expanding to new account codes, or tuning keyword triggers because too many entries land as UNCLASSIFIED (or the wrong account) Result: A per-client chart of accounts where every account row carries the keyword triggers the classification engine uses to pick it for incoming documents.

The chart of accounts is the second-priority match in the classification engine — after the vendor master. When a document doesn't hit a known vendor, the engine scans every keyword on every active chart-of-accounts row against the OCR'd line items and vendor name; the first hit wins and produces a MEDIUM confidence entry. Get the keywords right and you save reviewers time. Get them wrong and you either pile up UNCLASSIFIED entries or, worse, silently misclassify into the wrong account.

Before you start

• [ ] The client exists with Bookkeeping enabled (Settings → Enabled products).
• [ ] You have the client's chart of accounts to import — ideally a CSV exported from their existing accounting platform with columns for code, name, and type.
• [ ] You know the account types you'll use: ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE, TAX_PAYABLE, TAX_RECEIVABLE.
• [ ] You have an UNCLASSIFIED account seeded — the platform writes pending-review entries to a row with this account code, so the review UI can link to it.

TIP

If the client doesn't already maintain a clean chart of accounts, ask them to export it before you start. Adding a few accounts at a time as documents come in works, but it leaves a long tail of UNCLASSIFIED entries you'll have to retroactively reclassify.

Steps

1. Open Clients in the staff dashboard sidebar and click into your client.
2. Open the Chart of accounts tab on the client detail page.
3. Choose your path:

Bulk CSV upload (recommended for onboarding)

1. Click Upload CSV in the top right of the Chart of accounts panel.
2. Download the template if you haven't already — it shows the required columns: accountCode, accountName, accountType, keywords (semicolon-separated), and an optional taxCodeDefault.
3. Drag your CSV into the dialog and click Validate. The dialog shows row-by-row errors (duplicate codes, missing types, malformed keywords) inline.
4. Fix any errors and re-validate, then click Import. Rows with errors are skipped; valid rows land immediately.

Add or edit a single account

1. Click Add account in the top right.
2. Fill in:
   • Account code — the platform's identifier for this account (e.g. 6010, EXP-RENT). Must be unique per client.
   • Account name — human-readable label that appears in the journal entry table (e.g. Office rent).
   • Account type — pick from the dropdown.
   • Keyword triggers — comma-separated words or short phrases. Each keyword is matched case-insensitively as a substring against the document's vendor name and concatenated line-item text. Example: office rent, monthly rent, rental for the rent account.
   • Default tax code (optional) — e.g. SR (standard-rated 9% GST), ZR (zero-rated), EXEMPT. Used as the fallback tax code when the matching vendor master row doesn't carry one.
3. Click Save.

Deactivate an account

Open the row, click Edit, untick Active, save. Inactive accounts are skipped by the classification engine but are preserved on existing journal entries — no historical data is lost.

IMPORTANT

Keyword scope is the lever. Too broad (e.g. payment or bank) and the keyword fires on almost every document, misclassifying everything. Too narrow (e.g. only the full vendor name) and you'll never hit it because OCR rarely sees the exact same string twice. Aim for 3-6 short, specific phrases per account, drawn from words you'd expect on the actual document — e.g. for utilities: electricity, sp services, sp group, water, utility bill.

How to know it worked

1. The Chart of accounts tab lists every row with status, code, name, type, and a count of keywords.
2. The Setup health panel on the client's Overview tab flips Chart of accounts to green when at least one active account exists.
3. The activity log (sidebar → Activity log) shows bookkeeping.chart_of_accounts.imported with the row count, or bookkeeping.chart_of_accounts.entry_created for single adds.
4. Drop a test document in via Upload a document manually and confirm the resulting journal entry lands with MEDIUM confidence on the account you expect.

Common situations

If you see…	It means…	What to do
CSV import shows "Duplicate account code"	Two rows in the CSV (or one in the CSV vs. one already in the platform) carry the same code	Deduplicate the CSV, or remove the existing row first if you're replacing it
Most new entries land as UNCLASSIFIED despite a populated chart	Keywords are too narrow, or no row has the document's category at all	See Vendor-master match isn't firing — the same keyword diagnosis applies
A specific vendor lands on the wrong account every time	A keyword on a different account is firing first (engine takes the first match in iteration order)	Either tighten the offending keyword or add a vendor master row for that vendor — vendor master is Priority 1 and overrides keywords
You can't deactivate a row because "In use on N journal entries"	The platform refuses to hard-delete in-use rows	Edit and untick Active instead — historical entries keep their reference, future drafts skip the row

Related runbooks

• Add vendors to vendor master — Priority 1 match, runs ahead of chart-of-accounts keywords
• Review a journal batch — where bad classifications get caught
• Vendor-master match isn't firing — same diagnostic flow as keyword misses
• Bookkeeping SOP §4.2 — the full classification priority order