Public integration reference

Bufy integration reference

Complete reference for every Bufy server action. Use it to build mobile clients, automation, exports, or your own dashboards on top of your Bufy data.

Response envelope
Every action returns either { success: true, data: T } or { success: false, error: string }. Integrations should branch on success first. The error string is human-readable and safe to surface to end users.
Authentication
Call loginAction with { email, password } as FormData. On success the response contains the wrapped DEK and DEK salt; the server also sets an HTTP-only session cookie. All subsequent actions read the session from that cookie. Sessions idle-expire after 15 minutes of inactivity by default and absolutely expire after 24 hours. Call logoutAction to end the session explicitly.
Money and dates
Amounts are always integer cents (EUR) in transport and in storage. A €12.34 transaction is 1234 cents. Dates are ISO 8601 yyyy-mm-dd and always interpreted in the user's local timezone (Europe/Tallinn by default). Encrypted fields travel as 'ciphertext:iv' strings.
Authentication & account

Sign up, sign in, session management, password and account lifecycle.

Income sources

Recurring salary and other income streams that drive budget period calculations.

Recurring expenses

Fixed monthly obligations such as rent, loan payments, subscriptions and utilities.

Categories

User-defined spending categories. Each is tagged with a pillar (need / want / save) for 50/30/20 reporting.

Budget periods

A budget period is a payday-to-payday window. Active period drives the dashboard view.

Budget allocations

Per-category money envelopes for Zero-Based and Envelope users.

Transactions

Individual income, expense or transfer entries. These are the only things Bufy asks users to enter manually.

Investments & contributions

Manual investment tracker with XIRR money-weighted return computation.

Credit sources

Credit cards and other revolving credit lines. Used to compute utilisation and defer spending against free-to-spend.

Savings budgets

Dedicated saving goals (emergency fund, vacation, down payment). Tracked separately from spending categories.

Admin — user management

Admin-only operations for account and invite lifecycle. Requires the caller's email to be listed in ADMIN_EMAILS on the server.

Admin — invites & announcements

Invite code and system announcement management.