Practice Manager API
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
Endpoints
/firm-partners/workspace/reports/trial-balanceGenerates a trial balance as of a date.
/firm-partners/workspace/reports/pnlGenerates a profit and loss (income statement) for a date range.
/firm-partners/workspace/reports/balance-sheetGenerates a balance sheet as of a date.
/firm-partners/workspace/reports/aged-receivablesGenerates an AR aging report as of a date.
/firm-partners/workspace/reports/aged-payablesGenerates an AP aging report as of a date.
/firm-partners/workspace/reports/sales-by-product-serviceSummarizes invoice line revenue and quantity by product or service.
/firm-partners/workspace/reports/sales-by-customerSummarizes invoice line revenue and quantity by customer.
/firm-partners/workspace/reports/customer-reportReturns per-customer accounting activity with underlying journal entries.
/firm-partners/workspace/reports/account-transactionsReturns journal-line activity grouped by ledger account.
/firm-partners/workspace/reports/cash-flow-forecastForecasts the workspace's cash for the next 13 weeks, with optional what-if scenarios.
/firm-partners/workspace/reports/gst-returnCalculates the workspace's NZ GST return for a period. Nothing is saved or filed.
/firm-partners/workspace/reports/gst-audit-reportLists the transactions behind a period's NZ GST return, one page at a time.
/firm-partners/workspace/reports/depreciation-scheduleOne row per registered or disposed asset for a period, with depreciation, purchases and disposals in the period.
/firm-partners/workspace/reports/asset-registerThe asset register as of a date: cost, method, rate or life, accumulated depreciation and book value per asset.
/firm-partners/workspace/reports/fixed-asset-reconciliationCompares the general ledger's fixed asset accounts with the asset register for a period, by asset type.
