Transactions

A transaction is a single financial event — an expense, a purchase, or an income entry. ozzie-openapi uses AI to extract structured transaction data from natural language, images, PDFs, and spreadsheets via the stateless POST /v1/transactions/parse endpoint. Your application receives the parsed records and stores them.

What a parsed transaction contains

Field	Type	Description
amount_cents	integer	Amount in cents (always positive)
currency	string	ISO 4217 code (e.g. USD, BRL, EUR)
category	enum	Spending category (see below)
envelope	string	One of the six budget envelope keys
description	string	Short label extracted by AI (max 60 chars)
transaction_date	date	YYYY-MM-DD — extracted from input or defaults to today
ai_confidence	float	AI confidence score from 0.0 to 1.0

Categories

Ozzie classifies every transaction into one of 10 categories:

Category	Examples
food	Groceries, restaurants, coffee, delivery
transport	Gas, Uber, bus, parking, car maintenance
housing	Rent, mortgage, home repairs
utilities	Electricity, internet, water, phone bill
health	Doctor, pharmacy, gym, dental
entertainment	Streaming, movies, games, concerts
education	Courses, books, tuition, school supplies
clothing	Clothes, shoes, accessories
income	Salary, freelance, dividends, refunds
other	Anything that doesn't fit the above

Envelope mapping

Each transaction is automatically mapped to one of the six budget envelopes:

Category	Envelope
housing, utilities	bills
food, transport	daily_living
health	health_wellness
entertainment, education, clothing	lifestyle
gifts, family, social	people

Your application uses the envelope field to compute spending against the user's plan allocations.

Input sources

The POST /v1/transactions/parse endpoint accepts four input types:

Type	Format
text	Natural language string
image	Base64-encoded image (receipt or bank statement screenshot)
pdf	Extracted text from a PDF
spreadsheet	CSV rows as plain text

AI parsing

When you submit "Spent $45 on groceries at Whole Foods and $5 on coffee", the endpoint returns two transactions — not one. The AI extracts every financial event mentioned.

The ai_confidence score tells you how sure the AI was:

Score	Meaning
0.9 – 1.0	High confidence — clear amount, category, and date
0.7 – 0.89	Good — some inference was needed (e.g. currency from context)
0.5 – 0.69	Moderate — ambiguous input, may want to confirm with user
< 0.5	Low — could not extract reliably; consider re-prompting

How transactions fuel insights

Parse results that your application stores can feed into:

• Chat context — pass recent transactions in history or as system context in POST /chat/completion
• Plan tracking — compute actual spend vs. budgeted allocations using envelope and amount_cents
• Goal progress — track savings and debt payments over time
• Spending trends — aggregate by category or envelope across any date range

→ See Transactions API Reference