API Inputs

Request Inputs

This API generates an x-ray of one or two portfolios in a single request (POST /portfolioanalysis/v1/xray). The x-ray shows how each portfolio is diversified by region, sector, and investment style. Inputs are passed in the JSON request body, except langcult, which is a query parameter.

A maximum of 2 portfolios can be passed per request, with a maximum of 250 holdings per portfolio. The request body has four top-level fields. Portfolios and RequestSettings are required. Their inputs are described in the following sections:

• Request Settings Inputs
• Portfolio Inputs
• Holding Inputs
• Fee Inputs

{
  "View": { "Id": "All" },
  "RequestSettings": {
    "OutputCurrency": "USD",
    "AnalysisDateTimePeriod": "MonthEnd",
    "PortfolioPerformanceStartDate": "EarliestCommon"
  },
  "Portfolios": [
    {
      "Name": "ExamplePortfolio1",
      "Currency": "USD",
      "TotalValue": 50000,
      "Holdings": [
        { "TradingSymbol": "SPY", "Weight": 40 },
        { "ISIN": "US0378331005", "Weight": 50 },
        { "SecurityId": "CASH%0.000", "Weight": 10 }
      ]
    }
  ]
}

Config

Optional. Account-specific configuration preset, selected with the Id field. Settings from the preset can be overridden directly in the request.

langcult

Language and locale used for the response. To override the default value in the Accept-Language HTTP header, use this parameter.

Portfolios

Required. Array of portfolios to analyze.

RequestSettings

Required. Analysis settings including output currency, date range, performance frequency, and optional data sections.

View

Optional. Selects a predefined set of data points to return in the response, using the Id field.

Request Settings Inputs

These inputs are passed in the RequestSettings object.

AnalysisDateTimePeriod

Optional. End date period for the analysis. CustomDate requires PortfolioPerformanceEndDate to be set.

AssetClassGroupConfigs

Optional. Asset class group to query. The AssetClassGroupConfig array accepts a maximum of one value per request.

DisableRescale

Optional. When true, portfolio weights are not rescaled if any holdings are invalid or unentitled.

EnablePerformanceCommonEndDate

Optional. When true, the most recent common end date across all portfolios is used as the analysis end date.

IncludeGrossNetReturns

Optional. When true, both gross and net return values are included in trailing returns and calendar year return data.

IncludePortfolioInCorrelationMatrix

Optional. When true, the portfolio is included as an entry in the correlation matrix.

InitialValue

Optional. Initial value of the portfolio in the output currency.

MaxCorrelationMatrixHoldingNumber

Optional. Maximum number of holdings to include in the correlation matrix. Applies only when ReturnDataSections includes CorrelationMatrix.

OutputCurrency

Required. Currency used to calculate output values. 19 currencies are supported; accepted values are ISO 4217 currency codes.

PerformanceFrequency

Optional. Frequency of performance returns and risk calculations.

PortfolioPerformanceCustomStartDate

Custom start date of the analysis. Required when PortfolioPerformanceStartDate is set to CustomDate.

PortfolioPerformanceEndDate

End date of the analysis. Required when AnalysisDateTimePeriod is set to CustomDate.

PortfolioPerformanceStartDate

Optional. Start date of the analysis. CustomDate requires PortfolioPerformanceCustomStartDate to be set.

ReturnDataSections

Optional. Additional data sections to include in the response. Related inputs are RollingReturnFrequencies, RollingReturnStep, and MaxCorrelationMatrixHoldingNumber.

RollingReturnFrequencies

Rolling return periods to calculate. Required when ReturnDataSections includes RollingReturns.

RollingReturnStep

Optional. Step interval, in months, between rolling return calculations. Applies only when ReturnDataSections includes RollingReturns.

SynchronizePortfolioStartDate

Optional. When true, the latest common start date across all portfolios is used as the analysis start date for all portfolios.

Portfolio Inputs

These inputs are passed in each object of the Portfolios array.

Currency

Required. Portfolio currency. 19 currencies are supported; accepted values are ISO 4217 currency codes.

Fees

Optional. Portfolio-level annual fee configuration.

Holdings

Required. The holdings in the portfolio. Each holding must specify a security identifier and either Weight or Value.

IrrFees

Optional. Annual fee used in the internal rate of return calculation.

Name

Required. Portfolio name.

TotalValue

Total market value of the portfolio in the portfolio currency. Required when holdings use Weight. When holdings use Value, the sum of all holding values must equal TotalValue.

Holding Inputs

These inputs are passed in each object of the Holdings array.

Each holding requires one security identifier and one position size:

• Identifier: pass one of SecurityId, CUSIP, FundCode, ISIN, PerformanceId, or TradingSymbol. If multiple identifiers are provided for a single holding, SecurityId takes priority. If SecurityId is absent, the last identifier listed in the object is used. Identifier types can be mixed across holdings.
• Position size: pass either Weight or Value. The position size type must be the same for every holding in the portfolio.

Holdings can also include the annual fee inputs described under Fee Inputs.

CUSIP

Security's CUSIP.

FundCode

Security's fund code.

ISIN

Security's ISIN.

PerformanceId

Security's Morningstar Performance ID. Use the Universe API to retrieve Performance IDs for investments in your entitled universe.

SecurityId

Morningstar unique identifier of a security. Use CASH%0.000 for cash positions. Takes priority over any other identifier passed for the same holding.

TradingSymbol

Security's ticker or trading symbol.

Value

Market value of the holding in the portfolio currency. The sum of all holding values must equal the portfolio TotalValue. Use either Value or Weight, not both.

Weight

Holding weight as a percentage of the portfolio total. All holding weights must sum to 100, and the portfolio TotalValue is required. Use either Weight or Value, not both.

Fee Inputs

These inputs configure annual fees. They can be passed at the portfolio level, in the Fees object of a portfolio, or at the holding level, in an object of the Holdings array.

AnnualFeeFrequency

Optional. How often the annual fee is deducted. At the portfolio level the fee is deducted from the portfolio; at the holding level it is deducted from the holding.

AnnualFeePercent

Optional. Annual fee as a percentage of portfolio value (portfolio level) or holding value (holding level). For example, 1.15 is 1.15%.