Portfolio X-Ray API

Build Portfolio X-Ray APIs into your digital experience for quick investment and earnings summaries.

Request Structure

A Portfolio X-Ray request describes the portfolios you want to analyze and the settings that control the analysis. This page explains the structure of the request body and the rules for the portfolio portion of it: how holdings are identified, how positions are sized, and how fees are applied. For the settings that control the analysis itself, see Configuring the Analysis.

Top-Level Properties

The request body is a JSON object with the following top-level properties.

Property	Required	Description
`Portfolios`	Yes	An array of one or two portfolios to analyze.
`RequestSettings`	Yes	Analysis settings such as output currency, date range and optional data sections.
`View`	No	The predefined set of data points to return. Defaults to `All`.
`Config`	No	An account-specific configuration preset. Defaults to `Default`.

Request Limits

A request can include a maximum of 2 portfolios.
Each portfolio can contain a maximum of 250 holdings.

Defining a Portfolio

Each object in the Portfolios array has the following properties.

Property	Required	Description
`Name`	Yes	The portfolio name. The name is returned in the response as `PortfolioName`.
`Currency`	Yes	The portfolio currency, as an ISO 4217 code. See Supported currencies.
`Holdings`	Yes	An array of 1 to 250 holdings.
`TotalValue`	Conditional	The total market value of the portfolio in the portfolio currency. Required when holdings use `Weight`. Minimum 1.
`Fees`	No	Portfolio-level annual fee. See Adding fees.
`IrrFees`	No	The annual fee used in the internal rate of return calculation.

Identifying Holdings

Each holding must include one security identifier. The following identifiers are supported.

Identifier	Description	Example
`SecurityId`	Morningstar unique identifier of a security.	`FOUSA00DFS`
`CUSIP`	The security's CUSIP.	`09251T103`
`ISIN`	The security's ISIN.	`US0378331005`
`PerformanceId`	The security's Morningstar Performance ID.	`0P00002QN3`
`TradingSymbol`	The security's ticker or trading symbol.	`MDLOX`
`FundCode`	The security's fund code.	`ABG`

You can mix identifier types across holdings in the same portfolio. For example, one holding can use TradingSymbol and another can use ISIN.

If you provide more than one identifier for a single holding, SecurityId takes priority. If SecurityId is absent, the last identifier listed in the object is used. To avoid ambiguity, provide one identifier per holding.

To include a cash position, use the SecurityId value CASH%0.000.

Sizing Positions

Each holding must also include a position size, expressed as either Weight or Value. The position size type must be the same for every holding in a portfolio. You can use Weight in one portfolio and Value in another.

Position size	Rules
`Weight`	A percentage of the portfolio, from 1 to 100. Weights across all holdings must sum to 100. `TotalValue` is required on the portfolio.
`Value`	The market value of the holding in the portfolio currency. Minimum 1. Values across all holdings must equal the portfolio's `TotalValue`.

Supported Currencies

The portfolio Currency accepts the following 19 ISO 4217 codes: AUD, BRL, CAD, CHF, DKK, EUR, GBP, HKD, INR, JPY, MXN, MYR, NOK, NZD, SEK, SGD, TWD, USD and ZAR.

The same set of currencies is supported for OutputCurrency in the request settings.

Adding Fees

You can apply an annual fee to an entire portfolio, to individual holdings, or both.

Property	Level	Description
`AnnualFeePercent`	Portfolio (inside `Fees`) and holding	The annual fee as a percentage of value. For example, `1.15` represents 1.15%. Defaults to `0`.
`AnnualFeeFrequency`	Portfolio (inside `Fees`) and holding	How often the fee is deducted: `Monthly`, `Quarterly`, `SemiAnnually` or `Annually`. Defaults to `Monthly`.

Use IrrFees on the portfolio to set the annual fee used in the internal rate of return calculation.

Example Portfolio

The following portfolio uses Weight for position sizes, mixes a trading symbol with a cash position, and applies a portfolio-level fee.

{
  "Name": "ExamplePortfolio1",
  "Currency": "USD",
  "TotalValue": 50000,
  "Holdings": [
    { "TradingSymbol": "SPY", "Weight": 40 },
    { "TradingSymbol": "AGG", "Weight": 30 },
    { "TradingSymbol": "QQQ", "Weight": 20 },
    { "SecurityId": "CASH%0.000", "Weight": 10 }
  ],
  "Fees": {
    "AnnualFeePercent": 0.5,
    "AnnualFeeFrequency": "Monthly"
  }
}

To send this portfolio, add it to the Portfolios array along with the required RequestSettings. See Request Portfolio X-Ray for a complete request.