Users
For endpoint details, see the Users API Reference.
What is an Ozzie User?
In the Ozzie API, a user is not an authentication identity — it is a financial profile. When you create a user in Ozzie, you are creating a persistent record that accumulates financial data, a personalized plan, active goals, and behavioral history over time.
Think of a user as the financial "avatar" of one of your end-users inside the Ozzie platform. Ozzie does not manage login credentials or sessions. That responsibility stays with your application. Ozzie only manages what it knows about a person's financial life.
The Multi-Tenant Model
The Ozzie API is multi-tenant. Each API client (identified by your API key) operates in its own isolated namespace. Users you create are scoped entirely to your client — they are invisible to other API clients, and you cannot access users that belong to another client.
This means:
- You can create as many users as your plan allows.
- Each user belongs exclusively to your API client.
- There is no concept of "sharing" users across clients.
User Identity: Two IDs
Every Ozzie user has two identifiers:
| Field | Owner | Purpose |
|---|---|---|
external_user_id | You | Your internal ID for this person (e.g., your database UUID or customer ID) |
id | Ozzie | Ozzie's own UUID, auto-generated at creation |
You control external_user_id. You assign it at creation, and it must be unique within your API client. This is the primary key you will use to look up users — pass your own user ID and Ozzie resolves it to the correct financial profile.
The Ozzie id (UUID) is returned in all responses and can also be used for lookups, but most integrations find it more convenient to work with external_user_id.
Onboarding Stages
A user moves through three onboarding stages over their lifecycle:
financial_intake → plan → active
| Stage | What it means |
|---|---|
financial_intake | User has been created but has not yet submitted a financial intake (income, expenses, goal type) |
plan | Intake is complete; Ozzie has generated a personalized plan, but the user has not begun their first Money Moves cycle |
active | The user has at least one active goal and is receiving Money Moves |
Your integration should use the onboarding_stage field to guide users through setup flows. A user in financial_intake should be prompted to complete their intake before anything else is surfaced to them.
Language Preference
Users have a language_preference field that accepts en, pt, or es. This preference affects the language of:
- AI-generated plan descriptions
- Money Moves task copy
- Insight summaries
Set this field at creation time based on your user's locale, and update it if the user changes their language setting. Ozzie does not auto-detect language.
User Lifecycle
The typical integration flow looks like this:
Your app creates user → User completes intake → Plan is generated
↓
Goal is set → Money Moves begin → Transactions accumulate → Insights surface
When should you create users? You have two common options:
- At signup: Create the Ozzie user when your user signs up for your app. This is the cleanest approach and ensures the Ozzie profile is ready when needed.
- Lazy creation: Create the Ozzie user only when the user first accesses a financial feature. This is useful if only a subset of your users will engage with Ozzie-powered features.
Either approach works. What matters is that a user must exist in Ozzie before any financial data, goals, or plans can be associated with them.
Why This Matters for Your Integration
Understanding the user model shapes how you build:
- Routing: Use
external_user_idso you never have to store Ozzie's UUID in your database. - Onboarding gates: Check
onboarding_stageto decide which UI screens to show. - Localization: Set
language_preferencecorrectly at creation to ensure all AI content is in the right language from day one.