Skip to content
IndepAI API Docs

Calculate Portfolio Health Score

POST
/api/v1/portfolio-health

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

Request Body

Section titled “Request Body ”
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

object
success
required

Indicates successful calculation

boolean
data
required
object
totalScore
required

Overall health score (0-1000)

integer
<= 1000
Example
790
level
required

Portfolio health badge level based on total score

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

Diversification score (0-250)

integer
<= 250
Example
180
costEfficiency
required

Cost efficiency score (0-250)

integer
<= 250
Example
220
riskAlignment
required

Age-appropriate risk score (0-250)

integer
<= 250
Example
200
rebalancing
required

Rebalancing needs score (0-250)

integer
<= 250
Example
190
recommendations
required

Actionable improvement suggestions

Array<string>
Example
[
  "Consider adding international diversification",
  "Your expense ratios are excellent"
]
assetBreakdown

Breakdown of assets by type (percentage)

object
key
additional properties
number
Example
{
  "etf": 74,
  "stock": 18,
  "cash": 8
}
totalValue

Total portfolio value

number
Example
135000
meta
required
object
timestamp
required
string format: date-time
version
required
string

400

Section titled “400 ”

Validation error

object
success
required

Always false for error responses

boolean
error
required

Error type

string
Example
Validation error
code

Machine-readable error code

string
Example
VALIDATION_ERROR
details

Detailed validation errors

Array<object>
object
path
required

Path to the invalid field

string
Example
currentAge
message
required

Error message

string
Example
Must be between 18 and 100

429

Section titled “429 ”

Rate limit exceeded

object
success
required

Always false for error responses

boolean
error
required

Error type

string
Example
Validation error
code

Machine-readable error code

string
Example
VALIDATION_ERROR
details

Detailed validation errors

Array<object>
object
path
required

Path to the invalid field

string
Example
currentAge
message
required

Error message

string
Example
Must be between 18 and 100