API Reference
Reports
Generate trial balance, profit and loss, balance sheet, AR/AP aging, sales analytics, customer activity, account transactions (general-ledger detail), 13-week cash flow forecast, NZ GST return and GST audit reports, and the fixed asset depreciation schedule, asset register and reconciliation for a workspace.
Last updated 2026-11-19
Overview
The Reports API generates accounting reports for the authenticated workspace. The ledger reports are POST with report filters passed as query parameters and no JSON body — this keeps report generation read-only and compatible with MCP tool annotations. Three routes differ: the cash flow forecast is POST with an optional what-if `scenario` in the body, and the GST return and GST audit report are GET.
Account, tag, customer, vendor, product, and project filters accept comma-separated UUIDs from their respective list APIs. Do not pass internal numeric ids.
Key concepts
POST with query filters
Send POST with an empty body (or sign HMAC against `{}`). Put every filter on the query string — for example `?endDate=2026-03-31&transactionStatus=reviewed`.
Trial balance
Requires `endDate`. Without `startDate` the report runs as of `endDate`: balance sheet accounts are cumulative, income and expense accounts cover the current fiscal year, and earlier profit rolls into a synthetic Retained Earnings row (`id: "retained-earnings-synthetic"`). Each account row carries a net `debit` or `credit`, never both. Filter by account UUIDs, tags, transaction status, and account type.
Profit and loss
Requires `startDate` and `endDate`. Account rows sit under `categorized["Income"]`, `categorized["Cost of Goods Sold"]`, and `categorized["Operating Expense"]`. `grossProfit` is income minus cost of goods sold, `netProfit` also subtracts operating expenses, and both margins are percentages of income.
Balance sheet
Requires `endDate` as the as-of date. Returns `assets`, `equity`, and `liabilities` sections under `categorized`. Equity always ends with two synthetic rows: Retained Earnings through the prior fiscal year end (`synthetic-retained-earnings`) and Current Year Earnings (`synthetic-current-year-earnings`).
AR/AP aging
Aged receivables and aged payables compute open invoice/bill balances off the Accounts Receivable or Accounts Payable control account. Each response includes detail rows, counterparty summaries, bucket totals, and a reconciliation block against the control account GL balance.
Sales analytics
Sales-by-product/service and sales-by-customer summarize invoice line revenue and quantity over a date range. Customer activity is broader: it nets every journal entry linked to each customer (payments, tax, manual journals, expenses), not sales revenue alone.
Account transactions
The general-ledger detail report. Requires `startDate` and `endDate`, groups journal lines by ledger account, and returns opening/ending balances per account plus a running balance on each entry. Use `accountUuids` to pick the accounts and `categoryAccountUuids` to restrict the counterpart side. This is ledger activity — for bank/register rows use the Transactions API instead.
Cash flow forecast
Forecasts cash week by week for the next 13 weeks (Monday to Sunday) in the reporting currency at today's exchange rate. Inflows are open invoices, timed by each customer's historical days to pay, and upcoming recurring invoices; outflows are open bills by due date, detected recurring bank spend, payroll, and NZ GST on its IRD due date. Invoices already past their expected payment date are reported under `atRisk` and are not counted in the balance. Send a `scenario` to get a `scenarioForecast` beside the base `forecast`; a scenario changes nothing in the books.
GST return and GST audit report
NZ workspaces only. The GST return calculates the same figures as the GST return screen without saving or filing anything, and `reconciliation` says whether COUNT would let it file. When it would not, the GST audit report lists the transactions behind the return so you can find the one that is wrong. Both need the user to hold `file_gst_returns` or `view_reports`.
Fixed asset reports
The depreciation schedule (a period), asset register (as of a date) and fixed asset reconciliation (the register against the general ledger) read the asset register, so the user needs View Fixed Assets as well as the `reports:read` scope. Each row names its asset by UUID in `assetId`. Filters go in the query string or the JSON body.
Report response shapes
Each endpoint returns a generated report under `data`. Exact row shapes vary by report type.
Attributes
accounts / categorized / rowsobjectReport line items. Trial balance returns `accounts`; profit and loss and balance sheet nest account rows under `categorized` sections; aged receivables and payables return `rows` and `counterparties`.
totalsobjectSection or report-level totals.
filtersobjectThe filters a trial balance, profit and loss, or balance sheet ran with, including `currency` and the report dates.
currencystringReport currency (defaults to workspace currency). Trial balance, profit and loss, and balance sheet return it as `filters.currency`.
startDatedateReport period start when applicable.
endDatedateReport period end or as-of date.
{
"trialBalanceAccount": {
"id": "c8d9e0f1-a2b3-4567-cdef-789012345678",
"type": "Assets",
"name": "Business Checking",
"originalName": "Business Checking",
"systemCreated": false,
"accountNumber": "1000",
"subType": {
"id": 1,
"type": "Assets",
"name": "Cash and Bank",
"code": "CASH_AND_BANK",
"anchorTier": "PHYSICAL_ACCOUNT"
},
"debit": 39500
},
"profitAndLossAccountRow": {
"total": 45000,
"byTag": {},
"subAccounts": [],
"account": {
"id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"accountUuid": "d4e5f6a7-b8c9-0123-defa-234567890123",
"type": "Income",
"name": "Consulting Revenue",
"mask": null,
"status": "active",
"currency": "USD",
"originalName": "Consulting Revenue",
"connectionSyncEnabled": false,
"bookClosedBeforeDate": null,
"booksSealedThroughDate": null,
"providerAccountId": null,
"officialName": null,
"connectionOnlyAccount": false,
"isDeleted": false,
"isPayrollDefaultAccount": false,
"accountNumber": "4000",
"bankAccountNumber": null,
"bankName": null,
"govFundId": null,
"govSeg1Seg2Seg3Seg4Formatted": null,
"counterpartyTeamId": null,
"subType": {
"id": "01923a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
"type": "Income",
"name": "Income",
"description": "Revenue from the sale of goods and services.",
"anchorEligible": false,
"anchorTier": null,
"providerMatching": [],
"country": null,
"isDeleted": false,
"code": "INCOME",
"displayOrder": 1,
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-28T14:22:30.000Z"
},
"parentAccount": null
},
"income": 45000,
"byMonth": {
"2026-1": 15000,
"2026-2": 15000,
"2026-3": 15000
}
},
"balanceSheetAccountRow": {
"total": 39500,
"account": {
"id": 1187,
"name": "Business Checking",
"type": "Assets",
"accountNumber": "1000",
"originalName": "Business Checking",
"systemCreated": false,
"counterpartyTeamId": null,
"parentAccountName": null,
"parentAccountNumber": null,
"subType": {
"id": 1,
"name": "Cash and Bank",
"type": "Assets",
"code": "CASH_AND_BANK"
}
}
},
"agedReceivablesRow": {
"rowKey": "document:receivable:1042",
"source": "document",
"documentUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345",
"counterpartyUuid": "dfa3219e-6af8-4c53-997a-037534f63a35",
"counterpartyName": "Acme Corporation",
"documentNumber": "INV-1042",
"documentDate": "2026-03-01",
"dueDate": "2026-03-31",
"agingDate": "2026-03-31",
"ageInDays": -11,
"ageInMonths": 0,
"bucket": "notYetOverdue",
"bucketInMonths": "current",
"amount": 2500,
"unpaidTax": 200,
"documentStatus": "unpaid",
"documentType": "invoice",
"isCredit": false,
"description": "Consulting retainer",
"notes": null
}
}Use accountUuids not numeric ids
Pass comma-separated account UUIDs from the Chart of Accounts API via `accountUuids` or report-specific category filters.transactionStatus filter
Supported values: all, reviewed, unreviewed, reconciled, unreconciled.Related
Recent changes
Fixed assets
The asset register is on the Partner API and MCP. /partners/fixed-asset-types lists, gets, creates, updates and deletes asset types (each with its cost, accumulated depreciation and depreciation expense accounts and default depreciation settings). /partners/fixed-assets lists the register (status, type, search, sort, paging), gets one asset with its posted depreciation, updates and deletes drafts, merges two drafts (POST /merge-drafts) and projects depreciation (GET /{uuid}/projected-depreciation-schedule). POST /{uuid}/register, /unregister and /dispose run the lifecycle; a disposal posts its catch-up depreciation and journal together and refuses a sale missing the account its outcome needs. GET and POST /{uuid}/journal-links and DELETE /{uuid}/journal-links/{linkUuid} manage the journal lines behind an asset's cost, GET /{uuid}/audit-log returns its history, and /{uuid}/attachments lists, adds (multipart or URL) and deletes its files. GET /partners/fixed-asset-depreciation-rates returns the country's reference rates. POST /partners/reports/depreciation-schedule, /asset-register and /fixed-asset-reconciliation generate the fixed asset reports. Bill lines and transaction category changes accept `fixedAssetAssignment` with `fixedAssetUuid` / `fixedAssetTypeUuid`. These routes need the new `fixed-assets` scope (a bare `read` / `write` grant includes it; the reports need `reports:read`) plus View Fixed Assets to read and Administer Fixed Assets to change. The same routes work on client workspaces under /firm-partners/workspace. The MCP catalog adds 22 fixed asset tools and 3 report tools.
Cash flow forecast, GST return and audit report, tax codes, workspace events, and 17 MCP tools
Documented the six partner routes the reference was missing. POST /partners/reports/cash-flow-forecast forecasts cash for the next 13 weeks, with an optional what-if scenario (customer payment delays, bill payment dates and one-off or repeating adjustments) returned as scenarioForecast. GET /partners/reports/gst-return calculates an NZ GST return without filing it, including the reconciliation that decides whether COUNT would let it file, and GET /partners/reports/gst-audit-report lists the transactions behind it, flags the ones with a GST issue, and pages 200 rows at a time. GET /partners/taxes lists the workspace tax codes and their UUIDs. GET /partners/workspace-events returns what changed since the user last checked: invoices paid, failed invoice payments, new bills and bank feed syncs. GET /partners/journal-entries/{uuid} returns one posting with every line. Taxes and workspace events are also reachable through the Practice Manager client-workspace routes. npm run check:parity now reports 186 documented routes against 186 backend routes. The MCP catalog adds COUNT_list_taxes, COUNT_list_workspace_events, COUNT_get_journal_entry, COUNT_generate_cash_flow_forecast, COUNT_get_gst_return, COUNT_get_gst_audit_report, COUNT_propose_transaction_categories, four position tools (COUNT_get_all_positions, COUNT_create_position, COUNT_update_position, COUNT_delete_position), and five firm tools for client status and client questionnaires. COUNT_delete_project is now COUNT_archive_project, and DELETE /partners/projects/{uuid} is documented as the archive it is, with its real response (result.success). Also, COUNT_get_bulk_task_status, which the server no longer registers, is removed.
Response examples checked against the live API
Every Practice Manager route was called with a firm API key and the reference corrected where it disagreed. Tasks: the due date field is deadlineDate on create and update (deadline is ignored), firm-only tasks are never returned whatever visibility you pass, and creating a task with type INTERNAL_TASK leaves it unreachable through the API, so the examples now use type custom; the task object lists the fields the API returns. Response examples now match the API for the documents list (documents and pagination) and get (data.document), the projects, tasks, time entries and customers lists, and the trial balance, profit and loss, balance sheet and aged receivables and payables reports. Documents no longer list folderPath, mimeType or fileSize, which were never returned. Firm tasks: a malformed clientWorkspaceUuids filter returns 404, and customId is numbered per client workspace. The Idempotency-Key error applies to writes only.
Bill submit and refunds, reconciliation drafts, report filters, 30 MCP tools, and the Claude plugin
Documented the five partner routes the reference was missing: POST /partners/bills/{uuid}/submit, POST /partners/bills/{uuid}/assign-transaction (pay a bill, or refund a vendor memo with an income transaction), PATCH /partners/invoices/{uuid}/add-transactions (including credit memo refunds), and PATCH and DELETE /partners/reconciliations/{uuid} for correcting or discarding a draft. The account transactions report gains a reference-number range (checkNumberFrom/checkNumberTo) and the unknown-counterparty drill-down (unknownCustomerAr/unknownVendorAp), both accrual-only. Invoice and credit memo lines accept free-text Custom lines with categoryAccountUuid and name. Corrected the reference where it disagreed with the backend: dueDate is required on invoices and estimates, bills move through submitted and rejected as well as draft and approved, and a bill does have its own assign-transaction route. npm run check:parity now reports 178 documented routes against 178 backend routes. The MCP catalog adds 30 tools — customer contacts, addresses, notes, merge and revenue overview, GST settings, bill submit and memo refunds, reconciliation draft update/delete, COUNT_find_tool, COUNT_report_problem, and saved AI skills — moving the advertised count from 180 to 210. New pages cover the COUNT Claude plugin (/tools/claude-plugin) and the MCP brain, workspace memory and problem reports (/guides/mcp-brain-and-memory), and the FAQ gains the connector and API topics COUNT_knowledge serves to agents.
Account transactions report and a complete MCP tool catalog
Documented POST /partners/reports/account-transactions, the general-ledger detail report, which was the only backend partner route missing from the reference. Brought the MCP tool catalog back in line with the remote server: added the six report tools (aged receivables/payables, sales by product-service, sales by customer, customer activity, account transactions), ten remote-only Payroll tools covering people, pay stubs, PTO accrual caps, and locations, and a new remote-only Firm Practice Manager category of eleven firm-wide task, time-entry, and project tools. The advertised tool count moves from 153 to 180; the three deprecated-name invoice aliases stay excluded.
Complete Partner API reference
Documented all remaining API reference groups: Chart of Accounts, Vendors, Products & Services, Recurring Invoice Templates, Credit Memos, Bills, Journal Entries, Tags, People, Projects, Tasks, Time Entries, Expense Receipts, Reports, and Workspace Stats. Added missing invoice endpoints (audit log, attachments, credit application, remove transaction) and group overviews for Invoices and Transactions.
Endpoints
/partners/reports/trial-balanceGenerates a trial balance as of a date.
/partners/reports/pnlGenerates a profit and loss (income statement) for a date range.
/partners/reports/balance-sheetGenerates a balance sheet as of a date.
/partners/reports/aged-receivablesGenerates an AR aging report as of a date.
/partners/reports/aged-payablesGenerates an AP aging report as of a date.
/partners/reports/sales-by-product-serviceSummarizes invoice line revenue and quantity by product or service.
/partners/reports/sales-by-customerSummarizes invoice line revenue and quantity by customer.
/partners/reports/customer-reportReturns per-customer accounting activity with underlying journal entries.
/partners/reports/account-transactionsReturns journal-line activity grouped by ledger account.
/partners/reports/cash-flow-forecastForecasts the workspace's cash for the next 13 weeks, with optional what-if scenarios.
/partners/reports/gst-returnCalculates the workspace's NZ GST return for a period. Nothing is saved or filed.
/partners/reports/gst-audit-reportLists the transactions behind a period's NZ GST return, one page at a time.
/partners/reports/depreciation-scheduleOne row per registered or disposed asset for a period, with depreciation, purchases and disposals in the period.
/partners/reports/asset-registerThe asset register as of a date: cost, method, rate or life, accumulated depreciation and book value per asset.
/partners/reports/fixed-asset-reconciliationCompares the general ledger's fixed asset accounts with the asset register for a period, by asset type.
