Investment List API

Build the Investment List API into your digital experience for quick investment and earnings summaries.

Example Lists

View MarkdownDownload Markdown

This page has complete requests that you can adapt. Each example shows the request body for a common use, such as a performance watchlist or a fund due diligence list. To see how a request is built, see Request an Investment List.

Before You Use the Examples

  • Each example is the body of a POST request to the Investment List endpoint. Send it with your access token in the Authorization header and Content-Type: application/json.
  • Identifiers and values are illustrative. Replace them with investments from your own entitled universe.
  • Where an example identifies investments by ISIN, the entries set idType to isin. Entries with no idType are Morningstar Performance IDs.
  • If you aren't entitled to a data point, the row is returned without it, and metadata.messages lists the data point. See Work with Results.
  • A request can include up to 100 investments, 50 data points and 2 sort fields.

The following request shows how an example is sent. The body is the diversification and exposure example, shortened to a few data points.

curl --request POST \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investment-list" \
  --header "accept: application/json" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "investments": [
      { "id": "IE00B4L5Y983", "idType": "isin" },
      { "id": "LU0996182563", "idType": "isin" }
    ],
    "dataPoints": [
      "basicReference.fundLegalName",
      "morningstarCategory.globalCategory",
      "assetAllocationBreakdown.assetAllocEquityPercNet"
    ]
  }'

Examples at a Glance

ExampleWhat It Returns
Performance WatchlistIdentifiers and returns over several periods.
Diversification and Exposure WatchlistAsset allocation, regional, market capitalization and sector exposure.
Risk and Volatility WatchlistStandard deviation and risk statistics.
Equity Valuation WatchlistPrices, multiples, enterprise value and fair value.
Fund Due Diligence WatchlistFund attributes, fees, size, manager and returns.
Mix Identifier TypesSeveral identifier types, with lookup details.
Sort by Two Data PointsA primary and a secondary sort.

Performance Watchlist

Return identifiers and daily, trailing and month-end returns for a list of investments. This is a typical request for a watchlist or a comparison grid.

{
  "investments": [
    { "id": "0P000000YF" },
    { "id": "0P000000YD" },
    { "id": "0P000000YB" }
  ],
  "dataPoints": [
    "basicReference.name",
    "basicReference.ticker",
    "instrumentIdentifiers.isin",
    "reference.assetType",
    "reference.currency",
    "dailyReturnsMostRecent.returnDateDaily",
    "dailyReturnsMostRecent.totalRet1DayDaily",
    "dailyReturnsMostRecent.totalRet1WkDaily",
    "dailyReturnsMostRecent.totalRet1MoDaily",
    "dailyReturnsMostRecent.totalRetYtdDaily",
    "dailyReturnsMostRecent.totalRet1YrDaily",
    "trailingReturn.trailingReturnAsOfDate",
    "trailingReturn.trailing1MonthReturn",
    "trailingReturn.trailing3MonthReturn",
    "trailingReturn.trailing6MonthReturn",
    "trailingReturn.trailing1YearReturn",
    "trailingReturn.trailing3YearReturn",
    "trailingReturn.trailing5YearReturn",
    "monthEndTrailingPerformanceMonthEndAndQuarterEndMostRecent.returnDateMoEnd",
    "monthEndTrailingPerformanceMonthEndAndQuarterEndMostRecent.totalRet1YrMoEnd",
    "monthEndTrailingPerformanceMonthEndAndQuarterEndMostRecent.totalRetAnnlzd3YrMoEnd",
    "monthEndTrailingPerformanceMonthEndAndQuarterEndMostRecent.totalRetAnnlzd5YrMoEnd"
  ]
}

Diversification and Exposure Watchlist

Return the category, asset allocation, regional exposure, market capitalization and sector exposure for two funds, identified by ISIN.

{
  "investments": [
    { "id": "IE00B4L5Y983", "idType": "isin" },
    { "id": "LU0996182563", "idType": "isin" }
  ],
  "dataPoints": [
    "basicReference.fundLegalName",
    "basicReference.isin",
    "morningstarCategory.globalCategory",
    "assetAllocationBreakdown.assetAllocEquityPercNet",
    "assetAllocationBreakdown.assetAllocBondPercNet",
    "assetAllocationBreakdown.assetAllocCashPercNet",
    "assetAllocationBreakdown.assetAllocOtherPercNet",
    "countryAndRegionalExposureBreakdown.equityRegionUnitedStatesPercLongRescaled",
    "countryAndRegionalExposureBreakdown.equityRegionGreaterEuropePercLongRescaled",
    "countryAndRegionalExposureBreakdown.equityRegionGreaterAsiaPercLongRescaled",
    "countryAndRegionalExposureBreakdown.equityRegionEmergingPercLongRescaled",
    "marketCapitalBreakdown.marketCapLargePercLongRescaled",
    "marketCapitalBreakdown.marketCapMidPercLongRescaled",
    "marketCapitalBreakdown.marketCapSmallPercLongRescaled",
    "morningstarEquitySectorsBreakdown.equityEconSectorTechnologyPercLongRescaled",
    "morningstarEquitySectorsBreakdown.equityEconSectorFinancialServicesPercLongRescaled",
    "morningstarEquitySectorsBreakdown.equityEconSectorHealthcarePercLongRescaled"
  ]
}

Risk and Volatility Watchlist

Return standard deviation and risk statistics, such as beta, Sharpe ratio and capture ratios, for two investments identified by ISIN.

{
  "investments": [
    { "id": "US90214Q1058", "idType": "isin" },
    { "id": "US5949181045", "idType": "isin" }
  ],
  "dataPoints": [
    "basicReference.name",
    "instrumentIdentifiers.isin",
    "reference.assetType",
    "reference.currency",
    "dailyStandardDeviation.dailyStandardDeviationAsOfDate",
    "dailyStandardDeviation.standardDeviation252Day",
    "dailyStandardDeviation.standardDeviation756Day",
    "monthlyStandardDeviation.asOfDate",
    "monthlyStandardDeviation.standardDeviation36Month",
    "monthlyStandardDeviation.standardDeviation60Month",
    "riskStatistics.beta3YrMoEnd",
    "riskStatistics.rSquared3YrMoEnd",
    "derivedStatsIEMptCurrent.sharpeRatio3YrMoEnd",
    "riskStatistics.sortinoRatio3YrMoEnd",
    "riskStatistics.informationRatio3YrMoEnd",
    "riskStatistics.trackingError3YrMoEnd",
    "riskStatistics.upsideCaptureRatio3YrMoEnd",
    "riskStatistics.downsideCaptureRatio3YrMoEnd"
  ]
}

Equity Valuation Watchlist

Return the latest price, price multiples, enterprise value measures and the quantitative fair value for two equities identified by ISIN.

{
  "investments": [
    { "id": "US0378331005", "idType": "isin" },
    { "id": "US5949181045", "idType": "isin" }
  ],
  "dataPoints": [
    "companyInformation.standardName",
    "instrumentIdentifiers.isin",
    "reference.currency",
    "reference.marketSectorCode",
    "reference.marketSegmentCode",
    "closePrice.closePrice",
    "closePrice.closePriceDatetime",
    "performanceStatistics.percentChange",
    "priceMultiples.priceToEarningsRatio",
    "priceMultiples.priceToBookRatio",
    "priceMultiples.priceToSalesRatio",
    "priceMultiples.priceToCashFlowRatio",
    "priceMultiples.priceToFreeCashFlowRatio",
    "enterpriseValueCalculations.enterpriseValue",
    "enterpriseValueCalculations.enterpriseValueToEbitdaRatio",
    "enterpriseValueCalculations.enterpriseValueToRevenueRatio",
    "quantitativeRatings.quantitativePriceToFairValue",
    "quantitativeRatings.quantitativeValuationLabel",
    "quantitativeFairValues.quantitativeFairValue",
    "quantitativeFairValues.quantitativeFairValueDate"
  ]
}

Fund Due Diligence Watchlist

Return fund attributes, fees, size, manager details and returns for two funds identified by ISIN.

{
  "investments": [
    { "id": "IE00B4L5Y983", "idType": "isin" },
    { "id": "LU0996182563", "idType": "isin" }
  ],
  "dataPoints": [
    "basicReference.fundLegalName",
    "basicReference.isin",
    "basicReference.investmentType",
    "basicReference.domicile",
    "basicReference.inceptionDate",
    "basicReference.baseCurrency",
    "fundAttributes.activelyManaged",
    "fundAttributes.indexFund",
    "fundAttributes.openForInvestment",
    "annualReportFeesAndFinancialsMostRecent.totalExpenseRatio",
    "prospectusFees.prospectusGrossExpenseRatio",
    "prospectusFees.prospectusNetExpenseRatio",
    "feeLevelRanks.morningstarFeeLevelBroad",
    "netAssetsMonthEndMostRecent.netAssetsDate",
    "netAssetsMonthEndMostRecent.fundSize",
    "managerBioAndDetailsMostRecent.managerName",
    "managerBioAndDetailsMostRecent.managerTenureAverage",
    "monthEndTrailingPerformanceMonthEndAndQuarterEndMostRecent.totalRetYtdMoEnd",
    "monthEndTrailingPerformanceMonthEndAndQuarterEndMostRecent.totalRet1YrMoEnd"
  ]
}

Mix Identifier Types

Retrieve investments identified in different ways in one request. The first entry is a Performance ID, the default. The second is an ISIN. The third is a trading symbol, with lookup details that narrow the match to one exchange country and base currency.

{
  "investments": [
    { "id": "0P0000004Y" },
    { "id": "US5434957743", "idType": "isin" },
    { "id": "IBM", "idType": "tradingSymbol", "exchangeCountry": "USA", "baseCurrency": "USD" }
  ],
  "dataPoints": [
    "basicReference.name",
    "instrumentIdentifiers.isin",
    "reference.assetType",
    "reference.currency",
    "trailingReturn.trailing1YearReturn"
  ]
}

Because the rows don't repeat the identifiers you sent, the request includes instrumentIdentifiers.isin so you can match rows to your input. See Work with Results.

Sort by Two Data Points

Sort the rows by a primary and a secondary data point. Both must also be in dataPoints. The following request sorts by company ID ascending, then by one-day return descending.

{
  "investments": [
    { "id": "0P0000000F" },
    { "id": "0P0000001J" },
    { "id": "0P0000002I" },
    { "id": "0P0000003G" },
    { "id": "0P0000004E" }
  ],
  "dataPoints": [
    "companyInformation.companyId",
    "dailyReturnsMostRecent.totalRet1DayDaily",
    "basicReference.name",
    "reference.currency"
  ],
  "sort": [
    { "dataPoint": "companyInformation.companyId", "orderBy": "asc" },
    { "dataPoint": "dailyReturnsMostRecent.totalRet1DayDaily", "orderBy": "desc" }
  ]
}

Next Steps