Documentation Index
Fetch the complete documentation index at: https://mintlify.com/soker90/finper/llms.txt
Use this file to discover all available pages before exploring further.
Accounts and Transactions are the two foundational modules of Finper. An Account models a real-world bank account and tracks its running balance. A Transaction records every financial event against an account — whether money is coming in, going out, or simply being moved around internally. The two modules are tightly coupled: every transaction decrements or increments the balance of its linked account automatically, so your account balances always stay in sync with your recorded history.
Accounts
An Account represents a single bank or cash account owned by the authenticated user. Finper stores the current balance, the human-readable name, and the bank name. Accounts can be soft-archived by setting isActive: false — archived accounts are hidden from dashboards and budget calculations while preserving all historical transactions.
Endpoints
| Method | Path | Description |
|---|
POST | /api/accounts | Create a new account |
GET | /api/accounts | List all accounts for the current user |
GET | /api/accounts/:id | Retrieve a single account by ID |
PATCH | /api/accounts/:id | Partially update an account (name, balance, isActive) |
POST | /api/accounts/transfer | Transfer funds between two of your accounts |
Account Fields
| Field | Type | Required | Description |
|---|
name | string | ✅ | Human-readable label (e.g. "Checking", "Savings") |
bank | string | ✅ | Name of the bank or financial institution |
balance | number | ❌ | Initial balance, rounded to 2 decimal places (defaults to 0) |
isActive | boolean | ❌ | true by default; set to false to soft-archive the account |
Example: Creating an Account
curl -s -X POST http://localhost:3008/api/accounts \
-H 'token: <your-jwt>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Main Checking",
"bank": "My Bank",
"balance": 2500.00
}'
Example: Transferring Funds
The transfer endpoint moves money between two accounts atomically — it debits sourceId and credits destinationId by the same amount.
curl -s -X POST http://localhost:3008/api/accounts/transfer \
-H 'token: <your-jwt>' \
-H 'Content-Type: application/json' \
-d '{
"sourceId": "64a1f2e3b4c5d6e7f8a9b0c1",
"destinationId": "64a1f2e3b4c5d6e7f8a9b0c2",
"amount": 500.00
}'
The transfer creates a matching pair of transactions — one not_computable debit on the source account and one not_computable credit on the destination account — so the movement is visible in your transaction history without distorting income/expense totals.
Transactions
A Transaction records a single financial event tied to an account. Transactions are the primary source of truth for all budget comparisons, dashboard statistics, and subscription tracking in Finper.
Transaction Types
| Value | Meaning |
|---|
expense | Money leaving the account (e.g. grocery purchase) |
income | Money entering the account (e.g. salary, refund) |
not_computable | Movement that does not affect income/expense totals (e.g. internal transfers, account corrections) |
Endpoints
| Method | Path | Description |
|---|
POST | /api/transactions | Create a new transaction |
GET | /api/transactions | List transactions with optional filters |
PUT | /api/transactions/:id | Replace a transaction (full update) |
DELETE | /api/transactions/:id | Delete a transaction |
Transaction Fields
| Field | Type | Required | Description |
|---|
date | number | ✅ | Unix timestamp in milliseconds |
amount | number | ✅ | Transaction amount (positive value) |
type | string | ✅ | expense, income, or not_computable |
category | ObjectId | ✅ | Reference to a Category document |
account | ObjectId | ✅ | Reference to an Account document |
note | string | ❌ | Free-text note or description |
store | string | ❌ | Store or merchant name (auto-created if new) |
tags | string[] | ❌ | Up to 10 tags; each tag string max 30 characters |
subscriptionId | ObjectId | ❌ | Links this transaction to a recurring Subscription |
When you create a transaction and include a store name that does not yet exist in the database, Finper automatically creates the Store record for you. You never need to pre-register merchants manually.
Use not_computable for any movement that should appear in the transaction log but must not skew your income or expense calculations — for example, moving money between your own accounts or making a one-off balance correction.
Query Filters for GET /api/transactions
Pass the following query parameters to narrow down results:
| Parameter | Description |
|---|
date | Filter by exact date (Unix ms) |
account | Filter by account ID |
category | Filter by category ID |
type | Filter by transaction type (expense, income, not_computable) |
store | Filter by store ID |
page | Page number for pagination |
Example: Listing Transactions with Filters
curl -s "http://localhost:3008/api/transactions?account=64a1f2e3b4c5d6e7f8a9b0c1&category=64a1f2e3b4c5d6e7f8a9b0c3&page=1" \
-H 'token: <your-jwt>'
Stores
A Store represents a merchant or payee (e.g. "Whole Foods", "Amazon", "Landlord"). You never need to create stores directly — Finper creates them implicitly the first time a transaction references a new store name.
| Method | Path | Description |
|---|
GET | /api/stores | List all stores for the current user |
