SaaSFlow

Move one account into a different account group, or send `accountGroupId: null` to take it out of every group. Grouping is presentational and does not affect balances. Use `/accounts/reorder` when you also need to set the position inside the target group. Fails with 404 if the account or the group does not exist.

accounts_change_group

Create an account. Use `importType: "manual"` for one you will fill by hand or by CSV; accounts fed by a bank connection are created by the integration itself. `includeInCashBalance` decides whether it counts towards the cash position, which is usually false for loans. Pass `initialBalance` to seed the opening balance so the running balance is right from day one, dated before any transaction you then import. `order` is required and sets its position in the list.

accounts_create

Get the day-by-day cumulative balance across accounts, returned as `[date, balance]` tuples. Unlike the per-account balances endpoint, these are converted into the company's base currency and summed, so this is the series to plot as a cash curve. Restrict it to specific accounts with a comma-separated `accountIds`.

accounts_daily_balance

Delete an account and cascade-delete every transaction on it, along with their categorizations. That rewrites cash balances and the P&L for every period the account covered, so archive it instead when the intent is only to get it off the screen. Transfers in other accounts that were linked to it lose their link and show as open again; `GET /accounts/{accountId}/delete_preview` counts them beforehand.

accounts_delete

Preview what deleting an account would do to transfers in other accounts, without changing anything. Deleting an account removes its transactions, and a transfer in another account whose counterpart sat on it loses its link and shows as open again. That holds for direct links and for transfers routed through a transit account, whose transit bookings are removed as well. A counter transaction SaaSFlow created automatically for one of this account's transfers is deleted instead. Call this before `DELETE /accounts/{accountId}` to tell the user which accounts are affected.

accounts_delete_preview

Retrieve a single account with the integration managing it, if any. Returns 404 if the account does not exist or belongs to another company.

accounts_get

Get the account's initial-balance seed, the synthetic transaction that carries whatever the account held before its first imported transaction. Returns `{ transaction: null }` when no seed exists, which is the usual reason a running balance looks right in shape but wrong by a constant amount.

accounts_initial_balance

List a company's accounts (bank, cash, credit card, loan, transit, other) with the integration managing each one, where there is one. `includeInCashBalance` decides whether an account counts towards the cash position, so a loan or a holding account can be excluded from it. Archived accounts are included; filter on `archived` for the live ones. Transaction counts and last-transaction dates only appear for callers with `transactions:read`.

accounts_list

Permanently delete this one account's transactions before `beforeDate` and replace them with a single balance transaction, so the running balance stays correct while the detail goes away. Useful for trimming a long import back to the period the books actually start from. For the company-wide version that also sets the data start date, use `POST /accounts/remove_history`.

accounts_remove_history

Permanently delete transactions before `beforeDate` on the listed accounts and set the company data start date, so reporting begins from a clean, fully covered period. Each collapsed account gets an initial-balance seed so its running balance still ends up right; supply `initialBalances` for accounts with no existing seed, such as CSV wallets whose uploads started late, otherwise the seed is derived from the recorded sum. Pass an empty `accountIds` to only move the data start date. Accounts left with no transactions are archived and returned in `archivedAccountIds`. Transit accounts are refused with 422. This cannot be undone, so preview first.

accounts_remove_history_bulk

Preview what cutting off history before a date would do, without changing anything. Returns per-account transaction counts and date ranges, plus `suggestedDate`: the earliest date from which every account has data, which is the point where the books stop having gaps. Loan accounts are ignored when computing it, since their data only spans payout to final repayment and a late loan is not a coverage gap. Only accounts with transactions are listed, and transit accounts are left out. Always run this before `remove_history`.

accounts_remove_history_preview

Reorder accounts inside one group, and move them into it in the same call. Every id in `accountIds` is assigned to `accountGroupId` (null for the ungrouped list) and given an `order` matching its position, so send the full contents of the target group rather than just the account that moved. Fails with 404 if the group does not exist.

accounts_reorder

Set or correct the account's opening balance, creating the seed transaction if there is none. `value` is the balance on `date` in the account's default currency, not a delta. The date has to fall strictly before every other transaction on the account: otherwise you get 422 with `initial_balance_not_first` and the `earliestDate` to go before. Accounts managed by an integration that does not allow hand-set balances are refused with `integration_managed`.

accounts_set_initial_balance

Bring an archived account back into the active lists. Nothing about its transactions changes; only its visibility does.

accounts_unarchive

Update an account. Only the fields you send change. Two rules are enforced here: transit accounts may not change their type or currency (422), and a company can hold only one active transit account per currency, so creating a second is refused with 409 until the existing one is archived. Changing `defaultCurrency` on an account that already has transactions does not restate them.

accounts_update

Use this when the user asks for summary SaaS metrics (MRR, ARR, NRR, GRR, churn, LTV, CAC, burn rate, runway) over a period. Permissions are checked per requested metric: subscription metrics (MRR, ARR, churn, retention, growth) need subscriptions:read, P&L and cash metrics (revenue, margins, burn, runway) need financials:read, and metrics that combine both (CAC payback, LTV, Rule of 40, burn multiple) need both. Requires permissions: subscriptions:read, financials:read.

data_analytics

Retrieve one background task by id to check whether it is still running, what it produced, or why it failed. Returns 404 if the task does not exist or belongs to another company.

background_tasks_get

List background tasks for a company. Long-running work such as bank syncs, imports, and bulk edits runs asynchronously and reports progress here. Poll this after kicking off an operation that returns a task id, and read `status` to tell running from finished and failed. Tasks with `visible: false` are high-frequency webhook refreshes that the app hides from its pending indicator; skip them if you are mirroring that behaviour. Type-specific counters (processed, total, new transactions) live in `data`.

background_tasks_list

Use this when the user asks for cash/bank balances charted over time. Requires permissions: balances:read.

data_balanceTimeSeries

Use this when the user asks how balances are split across cash types (operating, reserve, savings, etc.). Requires permissions: balances:read.

data_balanceByCashType

Use this when the user asks how the company compares with SaaS peers: growth, retention, churn, gross margin, Rule of 40, CAC payback and burn multiple, each graded green, yellow or red against peer quartiles for the company's ARR stage and ACV segment. Pass arrStage or acvSegment to compare against another peer group. Permissions follow the metrics asked for, as in the analytics slice. Requires permissions: subscriptions:read, financials:read.

data_benchmarks

Use this when the user asks for cash inflows and outflows over time. Requires permissions: transactions:read, balances:read.

data_cashFlowTimeSeries

Use this when the user asks which categories drive cash inflows or outflows in a period. Requires permissions: transactions:read.

data_cashFlowByCategory

Delete several categories at once. All or nothing: if any id in the list is a system category, or still has transactions or planned transactions attached, nothing is deleted and the call fails with 400 or 409.

categories_batch_delete

Create a category. `plTypes` decides where transactions in it land in the P&L, and `order` sets its position in the list. Leave `system` at its default of false; system categories are SaaSFlow-managed and behave differently on delete.

categories_create

Delete a category. Refused with 409 while any transaction is still categorized under it or any planned transaction still uses it, and with 400 for system categories, which SaaSFlow manages. To retire a category that is in use, merge it into another one instead.

categories_delete

Retrieve a single category by id. Returns 404 if the category does not exist or belongs to another company.

categories_get

List a company's transaction categories. Each category declares the P&L lines it can post to through `plTypes` (revenue, cogs, cac, pd, ga, no, neutral), which is what lets one category split across the P&L. `used` counts everything currently assigned to the category, both transactions and planned transactions, so a zero there means the category can be deleted outright; `usedTransactions` and `usedPlannedTransactions` break that total down. Categories flagged `system` are created and maintained by SaaSFlow and cannot be deleted at all.

categories_list

Merge several categories into one, in a single transaction. Creates the category described by `newCategory`, then repoints everything that referenced the old ids: transaction categorizations, the default categorization on customers and vendors, and the default category on accounts. The old categories are deleted afterwards. This is how to retire duplicates without stranding history, since a plain delete is refused while transactions still use the category. One thing to know before running it: plan items on the old categories are deleted rather than repointed, so a merge drops that part of the financial plan. Returns the new category.

categories_merge

Set the display order of categories. Each id's `order` becomes its position in the array you send, so send the full list rather than the few you moved.

categories_reorder

Update a category's name, emoji, `plTypes`, or order. Only the fields you send change. Narrowing `plTypes` does not rewrite transactions already categorized under the removed P&L type, so check reporting after a change like that.

categories_update

Apply a reviewed batch of categorization suggestions in one call. Counterparties that do not exist yet go in `vendorsToCreate` and `customersToCreate` with a `tempId`; suggestions reference that same `tempId`, and the response maps each one to the real id it was created as. A suggestion pointing at a `tempId` that was never declared fails the whole request with 400. Creating counterparties needs `vendors:write` or `customers:write` on top of `transactions:write`. The result counts what landed and what was skipped. A transaction is skipped when it is unknown to this company, still pending, or already categorized, including by an earlier suggestion in the same request, so overlapping suggestions never silently overwrite each other.

categorization_suggestions_apply

Use this when the user asks which customers make up one cohort, or what is behind a single cell of the cohorts matrix. One cohort month and one target month per call; for the whole matrix use cohorts. Requires permissions: subscriptions:read, customers:read.

data_cohortCustomers

Use this when the user asks about customer retention or revenue retention by cohort. Returns the cohort matrix only (one entry per cohort month, MRR and customer count keyed by calendar month) and no customer rows, so it stays small enough to post-process. For the customers behind one cohort/month cell, use cohortCustomers. Requires permissions: subscriptions:read, customers:read.

data_cohorts

Post a comment on a transaction. `transactionId` is required and cannot be changed later. `taggedUserIds` records which teammates are mentioned, which is how the app renders @-mentions in the thread.

comments_create

Delete a comment. The transaction it was attached to is untouched. Returns success even when there was nothing to delete.

comments_delete

Retrieve a single comment by id, including who is tagged in it and who liked it. Returns 404 if the comment does not exist or belongs to another company.

comments_get

Add the calling user to a comment's likes. Idempotent: liking twice does not duplicate the user or inflate the count.

comments_like

List comments. Comments are always attached to a transaction, which is how teams discuss what a payment was for. Pass `transactionId` to get the thread on one transaction; omit it to get every comment in the company.

comments_list

Remove the calling user from a comment's likes. Idempotent: unliking a comment the user never liked is a no-op that still returns success.

comments_unlike