Compare Two Portfolios

A single request can include up to two portfolios. This lets you analyze, for example, a current portfolio and a proposed portfolio in one call. Each portfolio is analyzed independently and returned as its own object in the response.

Sending Two Portfolios

Add a second object to the Portfolios array. Each portfolio follows the same rules as a single portfolio, as described in Request Structure. The two portfolios can differ in the following ways:

• They can use different holding identifier types.
• They can use different position size types. One can use Weight while the other uses Value.
• They can have different TotalValue amounts and different fees.

Give each portfolio a distinct Name. The response uses the name to tell the portfolios apart.

Aligning the Analysis Periods

By default, each portfolio is analyzed over the period determined by its own holdings. Two portfolios can therefore have different performance start and end dates. To make the results comparable, use the following settings in RequestSettings.

You can use either setting on its own or both together.

Example Request

The following request compares an equity portfolio sized by Value with a mixed portfolio that includes a cash position. It aligns the start dates, requests rolling returns and selects an asset class group. See Asset Class Group Breakdown for the asset classes in each group.

{
  "RequestSettings": {
    "OutputCurrency": "USD",
    "AnalysisDateTimePeriod": "MonthEnd",
    "PortfolioPerformanceStartDate": "EarliestCommon",
    "PerformanceFrequency": "Monthly",
    "InitialValue": 10000,
    "SynchronizePortfolioStartDate": true,
    "ReturnDataSections": ["RollingReturns"],
    "RollingReturnFrequencies": ["Year1", "Year3", "Year5"],
    "RollingReturnStep": 1,
    "AssetClassGroupConfigs": {
      "AssetClassGroupConfig": [{ "Id": "ACG-USBROAD" }]
    }
  },
  "Portfolios": [
    {
      "Name": "ExamplePortfolio1",
      "Currency": "USD",
      "TotalValue": 50000,
      "Holdings": [
        { "TradingSymbol": "AAPL", "Value": 15000 },
        { "TradingSymbol": "MSFT", "Value": 12000 },
        { "TradingSymbol": "AMZN", "Value": 10000 },
        { "ISIN": "US5949181045", "Value": 8000 },
        { "TradingSymbol": "NVDA", "Value": 5000 }
      ],
      "Fees": {
        "AnnualFeePercent": 0.5,
        "AnnualFeeFrequency": "Monthly"
      }
    },
    {
      "Name": "ExamplePortfolio2",
      "Currency": "USD",
      "TotalValue": 19500,
      "Holdings": [
        { "TradingSymbol": "BND", "Value": 2000 },
        { "TradingSymbol": "VYM", "Value": 1500 },
        { "CUSIP": "922908769", "Value": 10000 },
        { "SecurityId": "CASH%0.000", "Value": 6000 }
      ]
    }
  ]
}

Reading the Results

The XRay array in the response contains one object per portfolio. Match each object to its portfolio using PortfolioName, and compare sections such as Analysis, Returns and Risks across the objects. Use PerformanceDate in each object to confirm the dates that were available for each portfolio.

The SecurityReference array is shared across the response and contains reference data for the securities in all portfolios. See Understanding the Response.

Invalid Holdings

If a holding in either portfolio is invalid or unentitled, the API rescales the portfolio weights by default. To receive an error that lists the affected holdings instead, set DisableRescale to true. See Request Portfolio X-Ray.