Skip to content
IndepAI API Docs

Calculate Portfolio Health Score

POST
/api/v1/portfolio-health
curl --request POST \
  --url https://indepai.app/api/v1/portfolio-health \
  --header 'Content-Type: application/json' \
  --data '{ "assets": [ { "type": "stock", "value": 100000, "symbol": "VWCE.DE", "name": "Vanguard FTSE All-World UCITS ETF", "quantity": 50, "purchasePrice": 110.5, "currency": "EUR", "expenseRatio": 0.22, "region": "Global" } ], "userAge": 35, "targetAllocation": { "stocks": 1, "etf": 1, "bonds": 1, "cash": 1, "crypto": 1, "real_estate": 1, "other": 1 }, "email": "hello@example.com", "saveResult": true }'

Calculate a health score for a portfolio based on diversification, cost efficiency, risk alignment, and rebalancing needs.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
assets
required

Array of portfolio assets

Array<object>
>= 1 items
object
type
required

Type of asset

string
Allowed values: stock etf crypto real_estate cash bond other
Example
etf
value
required

Current value in base currency

number
Example
100000
symbol

Ticker symbol (optional)

string
Example
VWCE.DE
name

Asset name (optional)

string
Example
Vanguard FTSE All-World UCITS ETF
quantity

Number of units held

number
> 0
Example
50
purchasePrice

Purchase price per unit

number
> 0
Example
110.5
currency

Currency code (ISO 4217)

string
default: EUR >= 3 characters <= 3 characters
Example
EUR
expenseRatio

Annual expense ratio for ETFs/funds (%)

number
<= 10
Example
0.22
region

Geographic region of the asset

string
Example
Global
userAge

User age for risk assessment (default: 35)

integer
default: 35 >= 18 <= 100
Example
35
targetAllocation

Target asset allocation for rebalancing analysis

object
stocks
number
<= 100
etf
number
<= 100
bonds
number
<= 100
cash
number
<= 100
crypto
number
<= 100
real_estate
number
<= 100
other
number
<= 100
email

Optional email to associate with the result

string format: email
saveResult

Whether to save result for analytics (default: true)

boolean
default: true

Responses

Section titled “Responses”

200

Section titled “200”

Health score calculation successful

Media typeapplication/json
object
success
required

Indicates successful calculation

boolean
data
required
object
totalScore
required

Overall health score (0-1000)

integer
<= 1000
level
required

Portfolio health badge level based on total score

string
Allowed values: Beginner Apprentice Competent Proficient Expert Master
components
required
object
diversification
required

Diversification score (0-250)

integer
<= 250
costEfficiency
required

Cost efficiency score (0-250)

integer
<= 250
riskAlignment
required

Age-appropriate risk score (0-250)

integer
<= 250
rebalancing
required

Rebalancing needs score (0-250)

integer
<= 250
recommendations
required

Actionable improvement suggestions

Array<string>
assetBreakdown

Breakdown of assets by type (percentage)

object
key
additional properties
number
totalValue

Total portfolio value

number
meta
required
object
timestamp
required
string format: date-time
version
required
string
Example
{
  "success": true,
  "data": {
    "totalScore": 790,
    "level": "Beginner",
    "components": {
      "diversification": 180,
      "costEfficiency": 220,
      "riskAlignment": 200,
      "rebalancing": 190
    },
    "recommendations": [
      "Consider adding international diversification",
      "Your expense ratios are excellent"
    ],
    "assetBreakdown": {
      "etf": 74,
      "stock": 18,
      "cash": 8
    },
    "totalValue": 135000
  }
}

400

Section titled “400”

Validation error

Media typeapplication/json
object
success
required

Always false for error responses

boolean
error
required

Error type

string
code

Machine-readable error code

string
details

Detailed validation errors

Array<object>
object
path
required

Path to the invalid field

string
message
required

Error message

string
Example
{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}

429

Section titled “429”

Rate limit exceeded

Media typeapplication/json
object
success
required

Always false for error responses

boolean
error
required

Error type

string
code

Machine-readable error code

string
details

Detailed validation errors

Array<object>
object
path
required

Path to the invalid field

string
message
required

Error message

string
Example
{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}