Skip to main content
POST
/
api
/
investment
/
:accountId
/
analyze-profile
Analyze Risk Profile
curl --request POST \
  --url https://api.example.com/api/investment/:accountId/analyze-profile \
  --header 'Content-Type: application/json' \
  --data '
{
  "age": 123,
  "monthlyIncome": 123,
  "jobStability": "<string>",
  "hasEmergencyFund": "<string>",
  "horizonYears": "<string>",
  "reactionToDrop": "<string>",
  "experienceLevel": "<string>",
  "financialMetrics": {
    "avgMonthlyIncome": 123,
    "avgMonthlyExpenses": 123,
    "savingsCapacity": 123,
    "savingsRate": 123,
    "historicalMonths": 123,
    "trend": "<string>",
    "deficitMonths": 123
  }
}
'
{
  "success": true,
  "data": {
    "recommendedProfile": "<string>",
    "confidence": 123,
    "reasoning": "<string>",
    "investmentPercentage": 123,
    "monthlyInvestable": 123,
    "liquidityReserve": 123,
    "historicalInsights": {
      "monthsAnalyzed": 123,
      "trend": "<string>",
      "bestMonth": "<string>",
      "worstMonth": "<string>",
      "savingsConsistency": "<string>"
    },
    "warnings": [
      {}
    ],
    "marketContext": "<string>"
  },
  "error": {
    "success": true,
    "message": "<string>"
  }
}
Analyzes user responses to generate a personalized investment risk profile using AI. The endpoint evaluates financial metrics, risk tolerance, investment experience, and time horizon to recommend an investment strategy.
This endpoint uses AI and counts as 1 AI request toward your rate limit.

​
Authentication

Requires a valid Bearer token in the Authorization header.

​
Path Parameters

​
accountId
string
required
The unique identifier of the account to analyze

​
Request Body

​
age
integer
required
User’s age (minimum 18, maximum 99)
​
monthlyIncome
integer
required
Monthly income in euros (must be positive, maximum 999,999)
​
jobStability
string
required
Employment stability levelOptions: high, medium, low
​
hasEmergencyFund
string
required
Whether user has an emergency fund establishedOptions: yes, partial, no
​
horizonYears
string
required
Investment time horizonOptions: <3, 3-10, >10
​
reactionToDrop
string
required
User’s typical reaction to a market downturnOptions: sell, hold, buy_more
​
experienceLevel
string
required
Investment experience levelOptions: none, basic, intermediate, advanced
​
financialMetrics
object
Optional calculated financial metrics for enhanced analysis

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
The AI-generated profile assessment results

​
Example Request

curl -X POST 'https://api.example.com/api/investment/acc_123/analyze-profile' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "age": 32,
    "monthlyIncome": 3500,
    "jobStability": "high",
    "hasEmergencyFund": "partial",
    "horizonYears": "3-10",
    "reactionToDrop": "hold",
    "experienceLevel": "basic",
    "financialMetrics": {
      "avgMonthlyIncome": 3500,
      "avgMonthlyExpenses": 2200,
      "savingsCapacity": 1300,
      "savingsRate": 37.14,
      "historicalMonths": 12,
      "trend": "stable",
      "deficitMonths": 1
    }
  }'

​
Example Response

{
  "success": true,
  "data": {
    "recommendedProfile": "balanced",
    "confidence": 0.85,
    "reasoning": "Based on your stable job, medium-term horizon, and willingness to hold during downturns, a balanced portfolio suits your profile. Your partial emergency fund should be completed before aggressive investing.",
    "investmentPercentage": 25,
    "monthlyInvestable": 325,
    "liquidityReserve": 6600,
    "historicalInsights": {
      "monthsAnalyzed": 12,
      "trend": "Stable savings pattern with consistent positive flow",
      "bestMonth": "Month 8 with 1,800€ saved",
      "worstMonth": "Month 3 with -150€ deficit",
      "savingsConsistency": "High - 11 out of 12 months positive"
    },
    "warnings": [
      "Complete your emergency fund to 3 months of expenses before increasing investment allocation",
      "Start with lower-risk investments given your basic experience level"
    ],
    "marketContext": "Current market volatility suggests starting with index funds and gradual position building"
  }
}

​
AI Provider Integration

This endpoint integrates with the configured AI provider (OpenAI, Anthropic, or Google) to analyze the user’s responses. The AI evaluates:
  • Risk tolerance based on behavioral responses
  • Financial capacity from income and metrics
  • Time horizon appropriateness
  • Experience level considerations
  • Current market conditions
The profile is saved to the database and used for future recommendations.

​
Error Responses

​
error
object

​
Common Errors

  • 400 - Invalid input data (validation failed)
  • 401 - Unauthorized (missing or invalid token)
  • 403 - Forbidden (no access to this account)
  • 503 - AI service unavailable

Build docs developers (and LLMs) love

Get started for freeTalk to us