Skip to main content

5-minute quickstart

This guide walks you through the full Ozzie onboarding sequence using ozzie-openapi directly: create a user, submit financial intake, score a personality quiz, generate a plan, and call the AI coach — all with real request and response examples.

All calls go to https://api.ozzieapp.com/v1.

Before you start​

You need a valid client_id and client_secret. Contact commercial@ozzieapp.com or log in to the Ozzie dashboard at Settings → API Keys.

Encode your credentials:

TOKEN=$(echo -n "your_client_id:your_client_secret" | base64)

Replace YOUR_BEARER_TOKEN in the examples below with your encoded token.

Step 1 — Create a user​

curl -X POST https://api.ozzieapp.com/v1/users \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "name": "Alex Johnson",
    "language": "en"
  }'

Response:

{
  "object": "user",
  "data": {
    "id": "ozz_usr_9f3a1b2c4d5e6f7a",
    "external_user_id": "user_123",
    "name": "Alex Johnson",
    "language": "en",
    "created_at": "2026-05-15T10:00:00Z"
  }
}

Save id — you'll use it in every subsequent call.

Step 2 — Submit financial intake​

curl -X POST https://api.ozzieapp.com/v1/users/ozz_usr_9f3a1b2c4d5e6f7a/financial-intake \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_income": 5000,
    "monthly_expenses": 3200,
    "financial_goal": "savings"
  }'

Response:

{
  "object": "financial_intake",
  "data": {
    "id": "ozz_intake_c8d4e2f1",
    "user_id": "ozz_usr_9f3a1b2c4d5e6f7a",
    "monthly_income": 5000,
    "monthly_expenses": 3200,
    "monthly_surplus": 1800,
    "financial_goal": "savings",
    "created_at": "2026-05-15T10:01:00Z"
  }
}

Step 3 — Score the personality quiz​

Get questions​

curl https://api.ozzieapp.com/v1/personality/questions \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Response (abbreviated):

{
  "object": "list",
  "data": {
    "questions": [
      {
        "id": "q_001",
        "text": "When you get extra money, what do you do first?",
        "options": [
          { "id": "q_001_a", "text": "Invest it right away" },
          { "id": "q_001_b", "text": "Move it to savings" },
          { "id": "q_001_c", "text": "Treat someone I love" },
          { "id": "q_001_d", "text": "Decide for myself" }
        ]
      }
    ],
    "total": 10
  }
}

Score answers​

curl -X POST https://api.ozzieapp.com/v1/personality/score \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      { "question_id": "q_001", "option_id": "q_001_a" }
    ]
  }'

Response:

{
  "object": "personality_score",
  "data": {
    "personality_type": "HOTSHOT",
    "score_breakdown": {
      "HOTSHOT": 7,
      "STOCKPILER": 1,
      "GIVER": 1,
      "INDEPENDENT": 1
    }
  }
}

Alex is a HOTSHOT — risk-tolerant and growth-oriented. Store personality_type in your database — you'll pass it on every subsequent intelligence call.

Step 4 — Generate the financial plan​

curl -X POST https://api.ozzieapp.com/v1/users/ozz_usr_9f3a1b2c4d5e6f7a/plan/generate \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "personality_type": "HOTSHOT" }'

Response:

{
  "object": "plan",
  "data": {
    "id": "ozz_plan_b1c2d3e4",
    "user_id": "ozz_usr_9f3a1b2c4d5e6f7a",
    "personality_type": "HOTSHOT",
    "plan_tier": "20/80",
    "envelopes": {
      "bills": { "allocated_pct": 40.0, "allocated_amount": 2000.00 },
      "future": { "allocated_pct": 20.0, "allocated_amount": 1000.00 },
      "daily_living": { "allocated_pct": 12.0, "allocated_amount": 600.00 },
      "health_wellness": { "allocated_pct": 6.0, "allocated_amount": 300.00 },
      "lifestyle": { "allocated_pct": 14.0, "allocated_amount": 700.00 },
      "people": { "allocated_pct": 8.0, "allocated_amount": 400.00 }
    },
    "action_items": [
      "Your $1,000 monthly savings target puts you on track to invest within 6 months.",
      "Your HOTSHOT profile means lifestyle spending is a valid priority — just keep it within the $700 envelope."
    ],
    "created_at": "2026-05-15T10:03:00Z"
  }
}

Store plan_tier — you'll use it when generating money moves.

Step 5 — Call the AI coach​

curl -X POST https://api.ozzieapp.com/v1/users/ozz_usr_9f3a1b2c4d5e6f7a/chat/completion \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How am I doing with my savings goal?",
    "personality_type": "HOTSHOT"
  }'

Response:

{
  "object": "chat_completion",
  "data": {
    "role": "assistant",
    "content": "Alex, your $5,000 income and $3,200 expenses leave you with $1,800 of disposable income. Your HOTSHOT plan targets $1,000/month to savings — which puts you on a 3-month path to having enough set aside before exploring investments. Keep that savings transfer automated on payday.",
    "created_at": "2026-05-15T10:04:00Z"
  }
}

What you just built​

In five steps you:

  1. Created a user (Alex Johnson)
  2. Submitted financial intake ($5,000 income, $3,200 expenses, savings goal)
  3. Scored a personality quiz → HOTSHOT
  4. Generated a personality-weighted plan with six envelope allocations
  5. Called the AI coach and received a data-grounded, personality-aware answer

Next steps​