Overview Accounts in Budget Bee are used to group and organize transactions. They represent different financial accounts like bank accounts, credit cards, or cash accounts.
The accounts resource is planned for future implementation. This documentation describes the intended API structure.
Base URL {NEXT_PUBLIC_PG_REST_URL}/accounts
Authorization All account endpoints require authentication via JWT token:
Authorization: Bearer {JWT_TOKEN}
Account Schema Unique account identifier
Account name (e.g., “Chase Checking”, “Amex Card”)
Detailed account description
Account type: checking, savings, credit_card, cash, investment
Account currency code (default: “usd”)
Financial institution name
Masked account number (last 4 digits)
Display color for the account (hex code)
Icon identifier for the account
Organization ID (null for personal accounts)
Additional metadata as JSON
When the record was created
List Accounts Retrieve all accounts for the authenticated user or organization.
Query Parameters Columns to return. Default: * (all columns)
Sort order. Example: name.asc or balance.desc
Request Example curl -X GET "{NEXT_PUBLIC_PG_REST_URL}/accounts?order=name.asc" \ -H "Authorization: Bearer {JWT_TOKEN}" \ -H "Content-Type: application/json"
Response Example [ { "id" : "acc_abc123" , "name" : "Chase Checking" , "description" : "Primary checking account" , "type" : "checking" , "currency" : "usd" , "balance" : 5420.50 , "institution" : "JPMorgan Chase" , "account_number" : "****1234" , "color" : "#0066CC" , "icon" : "building-columns" , "user_id" : "usr_abc123" , "organization_id" : null , "metadata" : { "routing_number" : "021000021" , "account_opened" : "2020-01-15" }, "created_at" : "2024-01-15T10:30:00Z" , "updated_at" : "2024-01-20T14:22:00Z" }, { "id" : "acc_def456" , "name" : "Amex Blue Cash" , "description" : "Cashback credit card" , "type" : "credit_card" , "currency" : "usd" , "balance" : -850.25 , "institution" : "American Express" , "account_number" : "****5678" , "color" : "#006FCF" , "icon" : "credit-card" , "user_id" : "usr_abc123" , "organization_id" : null , "metadata" : { "credit_limit" : 10000 , "apr" : 18.99 }, "created_at" : "2024-01-15T10:35:00Z" , "updated_at" : "2024-01-20T14:22:00Z" } ]
Get Account Retrieve a single account by ID.
GET /accounts?id=eq.{account_id}
Request Example curl -X GET "{NEXT_PUBLIC_PG_REST_URL}/accounts?id=eq.acc_abc123" \ -H "Authorization: Bearer {JWT_TOKEN}" \ -H "Accept: application/vnd.pgrst.object+json"
Response Example { "id" : "acc_abc123" , "name" : "Chase Checking" , "type" : "checking" , "balance" : 5420.50 , "currency" : "usd" , "institution" : "JPMorgan Chase" }
Create Account Create a new financial account.
Request Body Account type: checking, savings, credit_card, cash, investment
Currency code (default: “usd”)
Initial balance (default: 0)
Financial institution name
Request Example curl -X POST "{NEXT_PUBLIC_PG_REST_URL}/accounts" \ -H "Authorization: Bearer {JWT_TOKEN}" \ -H "Content-Type: application/json" \ -H "Prefer: return=representation" \ -d '{ "name": "Business Checking", "type": "checking", "currency": "usd", "balance": 10000.00, "description": "Main business account", "institution": "Bank of America", "account_number": "****9012", "color": "#CC0000", "icon": "briefcase", "metadata": { "routing_number": "026009593", "account_type": "business" } }'
Response Example { "id" : "acc_ghi789" , "name" : "Business Checking" , "type" : "checking" , "currency" : "usd" , "balance" : 10000.00 , "description" : "Main business account" , "institution" : "Bank of America" , "account_number" : "****9012" , "color" : "#CC0000" , "icon" : "briefcase" , "user_id" : "usr_abc123" , "organization_id" : "org_456" , "metadata" : { "routing_number" : "026009593" , "account_type" : "business" }, "created_at" : "2024-01-20T15:45:00Z" , "updated_at" : "2024-01-20T15:45:00Z" }
Update Account Update an existing account.
PATCH /accounts?id=eq.{account_id}
Request Example curl -X PATCH "{NEXT_PUBLIC_PG_REST_URL}/accounts?id=eq.acc_abc123" \ -H "Authorization: Bearer {JWT_TOKEN}" \ -H "Content-Type: application/json" \ -H "Prefer: return=representation" \ -d '{ "name": "Chase Primary Checking", "balance": 5650.75, "color": "#003D6F" }'
Response Example { "id" : "acc_abc123" , "name" : "Chase Primary Checking" , "balance" : 5650.75 , "color" : "#003D6F" , "updated_at" : "2024-01-21T09:15:00Z" }
Delete Account Delete an account permanently.
DELETE /accounts?id=eq.{account_id}
Request Example curl -X DELETE "{NEXT_PUBLIC_PG_REST_URL}/accounts?id=eq.acc_abc123" \ -H "Authorization: Bearer {JWT_TOKEN}"
Response Returns 204 No Content on successful deletion.
Consider the impact on transactions linked to this account. You may want to implement cascade delete or prevent deletion of accounts with transactions.
Account Types Checking Account { "type" : "checking" , "icon" : "building-columns" , "typical_balance" : "positive" }
Savings Account { "type" : "savings" , "icon" : "piggy-bank" , "typical_balance" : "positive" }
Credit Card { "type" : "credit_card" , "icon" : "credit-card" , "typical_balance" : "negative" }
Cash { "type" : "cash" , "icon" : "money-bill" , "typical_balance" : "positive" }
Investment { "type" : "investment" , "icon" : "chart-line" , "typical_balance" : "positive" }
Balance Calculation Automatic Balance Updates When linking accounts to transactions, balances can be automatically calculated:
-- Calculate account balance from transactions SELECT account_id, SUM ( CASE WHEN type = 'income' THEN amount ELSE - amount END ) as balance FROM transactions WHERE account_id = 'acc_abc123' GROUP BY account_id;
Manual Balance Adjustments You can also manually adjust balances:
PATCH /accounts?id=eq.acc_abc123
{ "balance" : 6000.00 , "metadata" : { "last_reconciled" : "2024-01-20" , "reconciliation_note" : "Manual adjustment after bank statement" } }
Access Control Account access follows the same role-based permissions as other resources:
Owner, Admin, Editor Full access: list, get, create, update, delete
Viewer Read-only: list, get
Best Practices Security
Never store full account numbers - Always mask sensitive dataEncrypt sensitive metadata - Use encryption for routing numbers and other sensitive infoLimit access - Use organization roles to control who can view/edit accounts
Organization
Use consistent naming - Follow a naming convention for accountsColor coding - Assign distinct colors to different account typesRegular reconciliation - Periodically verify balances match bank statements
Store additional information in the metadata field:
{ "metadata" : { "routing_number" : "021000021" , "account_opened" : "2020-01-15" , "credit_limit" : 10000 , "apr" : 18.99 , "rewards_program" : "cashback" , "last_reconciled" : "2024-01-15" , "plaid_item_id" : "item_xyz" } }
