Skip to main content

Financial Data

Ozzie works with financial data at two levels of granularity. Understanding the difference is key to building accurate integrations.

Two levels: aggregate and granular​

Monthly Intake (aggregate)        Transactions (granular)
─────────────────────────         ──────────────────────────
monthly_income:  $5,000           2024-01-03 Groceries     $45
monthly_expenses: $3,200          2024-01-05 Gas           $60
financial_goal:  "savings"        2024-01-08 Netflix       $15
                                  2024-01-12 Lunch         $18
                                  ...

Monthly intake is the macro snapshot — the "big picture" that drives plan generation. You submit it once (and refresh it when the user's situation changes). It tells Ozzie how much room the user has to work with each month.

Transactions are the micro level — individual expenses and income events parsed from natural language, images, PDFs, or spreadsheets using AI. ozzie-openapi parses them and returns structured records; your application stores them.

How they work together​

RoleData typeUsed for
Plan generationMonthly intakeComputing envelope allocations, plan tier, action items
Transaction parsingRaw text/image/PDFExtracting structured spending records with envelope mapping
Chat contextBothPass intake and recent transactions as context in POST /chat/completion

The intake sets the plan. Transaction parse results reveal reality. Your application compares them to provide meaningful feedback.

Immutability and history​

Monthly intake snapshots are never overwritten. Each POST /financial-intake creates a new record. The most recent snapshot is always used for plan calculations.

Currency handling​

Ozzie stores currency per transaction (ISO 4217 code: USD, BRL, EUR, etc.) inferred from the input by the AI parser. Monthly intake does not have an explicit currency field — it is assumed to be in the user's local currency. If your product serves multiple currencies, include currency context in the text input (e.g., "spent R$45 on groceries").

What this means for your integration​

  • Call POST /financial-intake once during onboarding, then refresh it when the user's income or expense profile changes significantly.
  • Call POST /v1/transactions/parse continuously — every time a user submits an expense, uploads a receipt, or sends a message. Store the returned transaction records in your database.
  • Pass recent transactions as context in POST /v1/users/:id/chat/completion for richer, data-grounded AI responses.

→ See Financial Intake API Reference and Transactions API Reference