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 / rowsobject

Report 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`.

totalsobject

Section or report-level totals.

filtersobject

The filters a trial balance, profit and loss, or balance sheet ran with, including `currency` and the report dates.

currencystring

Report currency (defaults to workspace currency). Trial balance, profit and loss, and balance sheet return it as `filters.currency`.

startDatedate

Report period start when applicable.

endDatedate

Report period end or as-of date.

Example
{
  "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.

Endpoints

POST
Generate trial balance/firm-partners/workspace/reports/trial-balance

Generates a trial balance as of a date.

POST
Generate profit and loss/firm-partners/workspace/reports/pnl

Generates a profit and loss (income statement) for a date range.

POST
Generate balance sheet/firm-partners/workspace/reports/balance-sheet

Generates a balance sheet as of a date.

POST
Generate aged receivables/firm-partners/workspace/reports/aged-receivables

Generates an AR aging report as of a date.

POST
Generate aged payables/firm-partners/workspace/reports/aged-payables

Generates an AP aging report as of a date.

POST
Generate sales by product/service/firm-partners/workspace/reports/sales-by-product-service

Summarizes invoice line revenue and quantity by product or service.

POST
Generate sales by customer/firm-partners/workspace/reports/sales-by-customer

Summarizes invoice line revenue and quantity by customer.

POST
Generate customer activity report/firm-partners/workspace/reports/customer-report

Returns per-customer accounting activity with underlying journal entries.

POST
Generate account transactions report/firm-partners/workspace/reports/account-transactions

Returns journal-line activity grouped by ledger account.

POST
Generate cash flow forecast/firm-partners/workspace/reports/cash-flow-forecast

Forecasts the workspace's cash for the next 13 weeks, with optional what-if scenarios.

GET
Get GST returnNZ· GST/firm-partners/workspace/reports/gst-return

Calculates the workspace's NZ GST return for a period. Nothing is saved or filed.

GET
Get GST audit reportNZ· GST/firm-partners/workspace/reports/gst-audit-report

Lists the transactions behind a period's NZ GST return, one page at a time.

POST
Generate depreciation schedule/firm-partners/workspace/reports/depreciation-schedule

One row per registered or disposed asset for a period, with depreciation, purchases and disposals in the period.

POST
Generate asset register/firm-partners/workspace/reports/asset-register

The asset register as of a date: cost, method, rate or life, accumulated depreciation and book value per asset.

POST
Generate fixed asset reconciliation/firm-partners/workspace/reports/fixed-asset-reconciliation

Compares the general ledger's fixed asset accounts with the asset register for a period, by asset type.