Skip to main content

Changelog

All notable changes to the Ozzie API are documented here. The Ozzie API follows Semantic Versioning. Breaking changes always result in a major version bump and are announced with a migration guide.

v1.0.0 — May 5, 2025​

Initial public release of the Ozzie API.

New endpoints​

Users​

  • POST /v1/users — Create a new user under your API client
  • GET /v1/users/{user_id} — Retrieve a user by ID
  • GET /v1/users — List users with optional external_user_id lookup

Financial Intake​

  • POST /v1/users/{user_id}/financial-intake — Submit or update a user's monthly financial snapshot (income, expenses, debt, primary goal)
  • GET /v1/users/{user_id}/financial-intake — Retrieve the user's current intake

Transactions​

  • POST /v1/users/{user_id}/transactions — Submit a transaction as text, image (receipt photo), PDF, or spreadsheet — Ozzie parses and categorizes all formats automatically
  • GET /v1/users/{user_id}/transactions — List transactions with filters for date range, category, and source type
  • GET /v1/users/{user_id}/transactions/{transaction_id} — Retrieve a single transaction

Goals​

  • POST /v1/users/{user_id}/goals — Create or replace the user's active goal
  • GET /v1/users/{user_id}/goals — Retrieve the user's current goal

Plan​

  • POST /v1/users/{user_id}/plan — Calculate or refresh the user's financial plan (requires intake)
  • POST /v1/users/{user_id}/plan/personalize — Adjust the plan's tone and recommendations based on a personality profile

Money Moves​

  • POST /v1/users/{user_id}/money-moves/generate — Generate the next money move cycle (requires plan)
  • GET /v1/users/{user_id}/money-moves — List cycles with status filter and cursor pagination
  • GET /v1/users/{user_id}/money-moves/{move_id} — Retrieve a single cycle
  • PATCH /v1/users/{user_id}/money-moves/{move_id} — Mark a cycle as completed or skipped

Chat​

  • POST /v1/users/{user_id}/chat/messages — Send a message to the AI financial coach — responses include reply, emotion, topic, and intent fields

Webhooks​

  • POST /api/webhooks/evolution — Inbound WhatsApp webhook via Evolution API — supports conversation (text) and imageMessage (receipt photo) message types

Features​

AI transaction parsing​

The POST /transactions endpoint accepts four input formats:

Source typeAccepted inputs
"text"Natural language descriptions (e.g., "spent $45 on groceries")
"image"Receipt photos in JPEG, PNG, or WebP format
"pdf"Bank statement or invoice PDFs
"spreadsheet"CSV or XLSX files with transaction rows

Ozzie's parser extracts merchant name, amount, date, and assigns a category automatically.

Multi-language support​

All AI-generated content (plan action items, money move tasks, chat replies, WhatsApp responses) is returned in the user's configured language. Supported languages at launch:

LanguageCode
Englishen
Portuguese (Brazilian)pt
Spanishes

Set the user's language on creation via POST /users using the language field. The AI coach will respond in that language for all subsequent interactions.

Personality-aware plans​

POST /plan/personalize supports four personality profiles that adjust the tone and pacing of all AI-generated content for that user:

ProfileDescription
optimizerData-focused; motivated by maximum efficiency and returns
plannerDetail-oriented; prefers structured roadmaps and predictability
avoiderMoney-anxious; responds to reassurance and small, achievable wins
spenderLifestyle-driven; needs strategies that don't feel like deprivation

Tiered access​

The Ozzie API is available on three tiers:

TierRate limitFeatures
Free100 requests/minUsers, Intake, Transactions (text only), Chat
Pro1,000 requests/minAll Free features + image/PDF/spreadsheet parsing, Money Moves, Goals, Plan personalization
EnterpriseCustomAll Pro features + SLA, dedicated support, custom rate limits, SSO

Contact commercial@ozzieapp.com to upgrade or discuss Enterprise pricing.

WhatsApp integration via Evolution API​

The inbound webhook at POST /api/webhooks/evolution handles the full message lifecycle:

  • Verifies the apikey header against EVOLUTION_WEBHOOK_SECRET
  • Routes messages to the correct Ozzie user by phone_e164
  • Processes text messages through the AI chat engine
  • Parses receipt images through the transaction image parser
  • Sends automatic replies through your Evolution API instance in the user's language

Known limitations at launch​

  • Chat does not retain conversation history between turns. Each message is processed independently with the user's full financial context but without memory of prior chat messages.
  • The WhatsApp webhook does not yet support PDF or spreadsheet file attachments sent via WhatsApp. Use POST /transactions directly for document uploads.
  • Plan generation is synchronous and typically takes 2–5 seconds. For high-traffic scenarios, consider calling this endpoint as part of an asynchronous job and caching the result.
  • POST /plan/personalize personality types are limited to the four profiles listed above. Custom personality types are planned for a future release.

Upcoming​

The following features are planned for upcoming minor releases. They are not yet available and are subject to change.

  • v1.1.0 — Conversation history: the chat endpoint will support an optional thread_id parameter that enables persistent, multi-turn conversations
  • v1.1.0 — Webhook support for WhatsApp audio messages (voice-to-text transaction logging)
  • v1.2.0 — GET /users/{user_id}/insights endpoint returning AI-generated monthly financial summaries
  • v1.2.0 — Additional personality types (minimalist, anxious-achiever)
  • v1.3.0 — Streaming chat responses via Server-Sent Events for real-time typewriter-style AI replies

Subscribe to the Ozzie developer newsletter to be notified when new features ship.

info

The Ozzie API adheres to a no-silent-breaking-changes policy. Any change that removes a field, changes a field's type, or alters the behavior of an existing endpoint will result in a major version bump (v2.0.0) with at least 90 days of deprecation notice and a published migration guide.