Introduction to the Ozzie API
Ozzie is a personal finance API that gives your application a fully functional AI-powered money coach. With a handful of REST endpoints, you can create users, ingest their financial data, generate personalized plans, and let them chat with an AI that understands their specific situation — without building any of that intelligence yourself.
The API is designed for developers who want to add real financial guidance to their products. Whether you're building a consumer app, an internal tool, or a WhatsApp bot, Ozzie handles the hard part: understanding a user's income, spending, and goals, then turning that into actionable advice and a structured financial plan.
Ozzie is multi-tenant by design. Your API credentials represent you as a platform — you create and manage users on behalf of your customers using an external_user_id that maps to your own user system. This means you stay in control of your user identities while Ozzie handles all the financial intelligence.
What you can build
- Fintech apps — embed a financial coach directly inside your mobile or web app, giving users personalized plans and real-time advice based on their actual spending
- WhatsApp bots — use the
/webhooks/evolutionendpoint to receive inbound WhatsApp messages and relay them to Ozzie's AI chat, creating a conversational money coach accessible from any phone - Analytics dashboards — aggregate financial intake and transaction data across your user base to surface trends, flag at-risk users, or build reporting tools
- Embedded coaches — add a chat interface to any existing product (banking app, HR platform, e-commerce checkout) that gives users contextual financial guidance in the moment they need it
Key concepts
| Concept | Description |
|---|---|
| Users | A user represents one of your customers in the Ozzie system. You create them with your own external_user_id so the mapping to your database stays in your hands. |
| Financial Intake | A monthly snapshot of a user's financial situation: income, total expenses, and their primary financial goal. This is the foundation that drives their plan. |
| Transactions | Individual expense records sent as text, an image (e.g., a receipt photo), a PDF, or a spreadsheet. Ozzie parses and categorizes them automatically. |
| Goals | A user's stated financial objective — for example "savings", "debt_payoff", or "investment". Goals shape the tone and recommendations of everything Ozzie produces. |
| Money Moves | Concrete, prioritized actions that Ozzie recommends based on a user's plan. Think of them as the to-do list that comes out of the financial analysis. |
| Plan | A generated financial plan for a user, derived from their intake and transaction history. Includes a summary, money moves, and a savings projection. |
| Chat | A conversational interface where users can ask questions, dig into their plan, and get real-time coaching from Ozzie's AI. Each message is contextualized by the user's financial data. |
API design principles
The Ozzie API follows a small set of conventions that apply everywhere:
REST and JSON — All endpoints accept and return JSON. Resources are addressed by path, and HTTP verbs map to actions in the standard way (POST to create or trigger, GET to retrieve).
Consistent response envelope — Every successful response wraps its payload in a top-level object field and a data field. Single resources look like { "object": "user", "data": { ... } }. Lists look like { "object": "list", "data": [...], "pagination": { ... } }.
Cursor-based pagination — List endpoints use cursor pagination rather than page numbers. The response includes has_more and next_cursor fields. Pass next_cursor as a query parameter to fetch the next page. This approach is stable even when new records are inserted between requests.
Idempotency — For create operations, using a consistent external_user_id means you can safely retry requests without creating duplicate users. For other mutating operations, Ozzie recommends you track request state on your side before retrying.
Predictable errors — All errors follow the same shape: { "error": { "code": "ERROR_CODE", "message": "...", "details": [...] } }. Error codes are machine-readable strings so you can handle them programmatically.
Quick links
- Authentication — get your credentials and learn how to sign requests
- Quickstart — create a user and generate their first plan in 5 minutes
- API Reference — full endpoint documentation with request/response schemas
- Postman Collection — import our pre-built collection and start making requests immediately