PocketSmith Complete Access

Permanently deletes an attachment. This action cannot be undone. Use list_attachments to find attachment IDs. Requires confirmation across two turns: call once without confirm to get a preview of what will be deleted, show the preview to the user, and wait for their reply. Only pass confirm: true after the user approves the previewed deletion in a later message - the user's original deletion request does not count as approval.

delete_attachment

Permanently deletes a category by its ID. This is irreversible. All transactions in this category will become uncategorized. Use list_categories to find category IDs. Requires confirmation across two turns: call once without confirm to get a preview of what will be deleted, show the preview to the user, and wait for their reply. Only pass confirm: true after the user approves the previewed deletion in a later message - the user's original deletion request does not count as approval.

delete_category

Deletes a budget event. The behaviour parameter controls whether to delete just this event ('one'), from this event forward ('forward'), or all events in the series ('all'). This action cannot be undone. Requires confirmation across two turns: call once without confirm to get a preview of what will be deleted, show the preview to the user, and wait for their reply. Only pass confirm: true after the user approves the previewed deletion in a later message - the user's original deletion request does not count as approval.

delete_event

Clears the forecast cache for a user, forcing budget forecasts to be recalculated. Use after bulk-creating or bulk-editing events. PocketSmith recalculates automatically for single changes, so this is only needed after batch operations.

delete_forecast_cache

Permanently deletes a financial institution and all its accounts, transaction accounts, and transactions. This is irreversible. Optionally merge into another institution instead of deleting. Use list_institutions to find institution IDs. Requires confirmation across two turns: call once without confirm to get a preview of what will be deleted, show the preview to the user, and wait for their reply. Only pass confirm: true after the user approves the previewed deletion in a later message - the user's original deletion request does not count as approval.

delete_institution

Permanently deletes a transaction by its ID. This is irreversible. Use list_transactions to find transaction IDs. Requires confirmation across two turns: call once without confirm to get a preview of what will be deleted, show the preview to the user, and wait for their reply. Only pass confirm: true after the user approves the previewed deletion in a later message - the user's original deletion request does not count as approval.

delete_transaction

Point-in-time financial health check. Returns net worth, cash position (liquid accounts), current month spending pace with projection and last-month comparison, per-category budget traffic lights (on_track/at_risk/over_budget) with each category tagged is_bill to distinguish bills from discretionary budgets, action items (uncategorized and needs-review counts), and upcoming events in the next 14 days split into bills and budget events. Ideal for a quick daily or weekly check-in or a broad 'how am I doing financially' RIGHT NOW. For a one-period retrospective use month_end_review; to compare two periods use spending_comparison; for just the upcoming events list use list_events.

financial_health_snapshot

Detects recurring expenses (subscriptions, memberships, regular bills) by analyzing transaction history. Groups transactions by payee, identifies regular intervals and consistent amounts, and classifies frequency (weekly, monthly, quarterly, etc.). Returns estimated annual cost per item and totals. Useful for subscription audits, finding forgotten recurring charges, and 'am I paying too much for X' policy/premium comparisons. No report page maps to subscriptions — answer from this data directly rather than offering a navigation link.

find_recurring_expenses

Compares actual vs forecast account balances over a past period to evaluate how reliable the user's forecasting has been. Also analyses budget data to identify inaccuracy drivers — categories that are unbudgeted (spending with no budget), significantly underbudgeted (actual exceeds forecast by 25%+), or significantly overbudgeted (forecast exceeds actual by 2x+). Note: forecast values for past dates reflect the CURRENT scenario settings, not what was originally forecast. This is useful for calibrating current forecast configuration. Accounts without linked scenarios will have no forecast data for comparison.

forecast_accuracy

Gets an account by its ID. An account is a container that groups one or more transaction accounts (where transactions live) and scenarios (where budget forecasts live). Most accounts have a single transaction account, but some (e.g. a mortgage with offset) have multiple. Returns the account's title, type, currency, current balance, and its child transaction accounts and scenarios.

get_account

Gets an attachment by its ID. Returns the attachment's title, file name, content type, and download URL.

get_attachment

Gets the user's budget for their configured forecast period — one entry per category with budgeted vs actual figures, the data behind the Budget page's per-category list. Optionally rolls up child categories into their parents. Use get_budget_summary for analysis over a specific date range; navigate_to_budget is the matching page link to offer alongside an answer.

get_budget

Gets the user's budget summary with expense and income analysis across all categories (excluding transfers) for a given date range and period. Returns actual vs budgeted figures per period bucket — the only analysis tool with sub-monthly buckets (weekly, or fortnightly via period=weeks interval=2), so use it for pay-cycle asks like 'what's left over each fortnight'. navigate_to_budget (manage) or navigate_to_income_expense (statement) is the matching page link to offer alongside an answer.

get_budget_summary

Gets a category by its ID. Returns the category's title, colour, parent category (if any), and whether it is a transfer or bill category.

get_category

Gets a specific currency by its code (e.g. 'nzd', 'usd'). Returns the currency's name, symbol, and decimal places.

get_currency

Gets the currently authenticated PocketSmith user. Returns the user's ID, name, email, time zone, currency, and account metadata. Use this to obtain the user ID needed by most other tools.

get_current_user

Lists all data feed connections for a user with their sync status, including last successful sync time, next sync time, and provider details. Optionally includes per-connection account details (balances, transaction update times). Use this to check if feeds are healthy, degraded, or need attention.

get_data_feeds_connection_status

Gets a budget event by its ID. Events represent recurring or one-off income/expense entries used in budget forecasting. The ID format is 'number-timestamp' (e.g. '42-1601942400').

get_event

Gets a financial institution by its ID. Returns the institution's title, currency, and creation date.

get_institution

Gets a single transaction by its ID. Returns the transaction's date, payee, amount, category, labels, note, memo, and review status.

get_transaction

Gets a transaction account by its ID. A transaction account is where transactions are recorded. It belongs to a parent account (container) and optionally links to an institution. Each account has one or more transaction accounts. Returns the account name, number, type, currency, current balance, and starting balance.

get_transaction_account

Gets income and/or expense budget trend analysis for a date range and period — the data behind the Trends report (per-bucket actual vs budget for chosen categories over time). Analyses across specified categories and all user scenarios by default. navigate_to_trends is the matching page link to offer alongside an answer.

get_trend_analysis

Lists accounts. Requires either user_id or institution_id. Each account is a container grouping one or more transaction accounts (where transactions live) and scenarios (where budget forecasts live). Use get_current_user for user IDs, list_institutions for institution IDs.

list_accounts

Lists attachments. Requires either user_id or transaction_id. When filtering by user, optionally return only unassigned attachments.

list_attachments

Lists all categories belonging to a user. Categories are hierarchical - each category may have a parent and children. Returns each category's ID, title, colour, type, and parent relationship.

list_categories

Lists all category rules belonging to a user. Category rules automatically assign categories to transactions based on payee matching patterns.

list_category_rules

Lists all currencies supported by PocketSmith. Returns currency codes, names, and symbols.

list_currencies

Lists budget events within a date range. Requires either user_id or scenario_id. Events represent recurring or one-off income/expense entries used in budget forecasting. A scenario belongs to an account and contains the events that drive its forecast.

list_events

Lists all financial institutions belonging to a user. Each institution represents a bank or financial provider and contains one or more accounts.

list_institutions

Lists all labels belonging to a user. Labels are free-form tags that track things ACROSS categories — commonly tax-deductible, reimbursable, or per-project expenses — so check here when a 'pull together my work expenses' style ask has no matching category (list_transactions search matches label text). Labels are created implicitly when first added to a transaction via create_transaction or update_transaction.

list_labels

Lists saved searches belonging to a user. Saved searches are pre-configured transaction filters. They cannot be executed via the API - use the returned filter criteria with list_transactions manually, or open one in the app by passing its numeric ID as the token to navigate_to_transactions.

list_saved_searches

Lists all time zones supported by PocketSmith.

list_time_zones

Lists all transaction accounts for a user. Transaction accounts hold the actual transactions. Each belongs to a parent account (container). Use get_current_user to obtain the user ID.

list_transaction_accounts

Lists transactions with pagination (default 30/page, max 100). Requires at least one of user_id, account_id, category_id, or transaction_account_id. Supports date range, type, category status, review status, and keyword search. Search terms are space-separated and ANDed: each word is substring-matched across date, amount, account name, payee, category title, note and labels, so multi-word queries refine accurately (e.g. 'epartner 36' = payee fragment + amount fragment; 'epartner 3d' = payee + label). Every word must literally appear in some field though — filler words like 'refund' or 'reimbursement' match nothing unless they're in the payee/note. The richer in-app search (duplicate/transfer specials, saved searches, category-scoped tokens) is not available via the API — offer navigate_to_transactions for those. Use get_current_user for user IDs, list_accounts for account IDs, list_categories for category IDs, list_transaction_accounts for transaction account IDs.

list_transactions

Comprehensive financial review for any date range. Returns income/expense summary with prior-period comparison, savings rate, per-category budget variance (each category tagged with is_bill to distinguish bills from discretionary budgets), top payees, notable transactions, net worth snapshot, upcoming obligations split into bills and budget events, and housekeeping counts. Ideal for a retrospective on ONE period — monthly reviews, quarterly check-ins, 'where did my money go last month'. To compare TWO periods use spending_comparison; for a right-now health check use financial_health_snapshot. The output is structured for easy summarization and sharing with household members. navigate_to_income_expense is the matching page link to offer alongside an answer.

month_end_review

Deep link to the Account Summary (/account_summary/:year/:month/:id) — every account's balance and recent activity (one card per account/group, organised by bank) as of a chosen month. Pick this for account-balance asks: 'how much is in my savings', 'my ANZ balance', 'show me my accounts', 'what were my account balances at the end of March'. For overall worth (assets minus debts) or its trend use navigate_to_net_worth; for money in/out use navigate_to_cashflows. There is no single-account filter — the page shows all accounts; pass institution_id to narrow to one bank when it's known. Omit year/month for current balances.

navigate_to_account_summary

Deep link to the Budget page (/budget) — the hub for tracking and managing budgets in ONE period. Shows a combined income+expense Total Budget Summary (progress bars: budgeted vs earned/spent, surplus/deficit, rollover) plus the full per-category budget table (Category, Budget, Amount, Roll-Up). Pick this for how-am-I-tracking-right-now asks: 'am I on budget this month', 'how much is left in my grocery budget', 'show my budget', 'which budgets am I blowing', or anything about creating or adjusting budgets and rollover. For how a category trends over time use navigate_to_trends; for an actual-vs-budget breakdown read-out across all categories use navigate_to_income_expense. Lands on the whole budget (no single-category filter).

navigate_to_budget

Deep link to the Calendar (/calendars) — a month grid of scheduled/forecast budget events (upcoming bills, expected income, transfers) on the days they fall due, with a projected daily closing balance. Forward-looking (past actuals are off by default). Pick this for day-level, event-centric 'what's coming up' asks: 'what bills are due this month', 'when's my next paycheck', 'my upcoming/scheduled transactions', 'which day will my account go negative'. For an aggregate cash projection over several months use navigate_to_cashflows; for actual past records use navigate_to_transactions. group_ids/account_ids/scenario_ids are the items to SHOW (the app inverts them internally — always pass what you want visible). Omit year/month for the current month.

navigate_to_calendar

Deep link to the Cashflows statement (/cashflows) — a month-by-month spreadsheet-style TABLE (not a chart) of forecast vs actual money in/out per category, ending in each month's projected/actual closing balance and surplus/deficit. Future months show forecast only; the start_date+end_date pair sets the month columns and can span any horizon (multiple years is fine, past or future). Pick this for projection / affordability / liquidity asks: 'what will my balance be at Christmas', 'will I run low over the next few months', 'can I afford X later this year', 'monthly surplus/deficit', forecast-vs-actual by month. For category spend analysis use navigate_to_income_expense or navigate_to_trends; for overall wealth use navigate_to_net_worth; for a day-level list of upcoming events use navigate_to_calendar. Needs an explicit start_date+end_date pair (named ranges aren't resolved here).

navigate_to_cashflows

Deep link to the Income & Expense report (/income_expense) — a profit & loss statement for personal finances: budget-vs-actual across ALL categories for ONE period (a range is aggregated into a single column set, NOT a time series). Income and Expense sections, one row per category (Budgeted, Actual, Difference, optional % and Rollover), with subtotals and a Net Income total. Pick this for breakdown / where-did-it-go asks: 'where did my money go last month', 'how much did I earn vs spend', 'which categories am I overspending in', 'what share of my spending is rent', or any P&L / statement request. For ONE category's trend over time use navigate_to_trends; to manage budgets use navigate_to_budget; for the raw transactions use navigate_to_transactions. only_category_ids and group_ids are the items to SHOW (the app inverts them — pass what you want visible).

navigate_to_income_expense