--- title: "Example Lists" description: "Complete Investment List API requests you can adapt: performance, exposure, risk, valuation and due diligence watchlists, plus mixed identifiers and sorting." url: "https://developer-beta.morningstar.com/investment-list-api/example-lists" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RXhhbXBsZSBMaXN0cyB8IEludmVzdG1lbnQgTGlzdCBBUEk,description_~Q29tcGxldGUgSW52ZXN0bWVudCBMaXN0IEFQSSByZXF1ZXN0cyB5b3UgY2FuIGFkYXB0OiBwZXJmb3JtYW5jZSwgZXhwb3N1cmUsIHJpc2ssIHZhbHVhdGlvbiBhbmQgZHVlIGRpbGlnZW5jZSB3YXRjaGxpc3RzLCBwbHVzIG1peGVkIGlkZW50aWZpZXJzIGFuZCBzb3J0aW5nLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9pbnZlc3RtZW50LWxpc3QtYXBpL2V4YW1wbGUtbGlzdHMi,s_yEx6kJ6g1Agq5VNt.png" --- - [APIs](https://developer-beta.morningstar.com/apis) - [API Catalog](https://developer-beta.morningstar.com/api-catalog) - [API Assistant MCP Server](https://developer-beta.morningstar.com/api-assistant-mcp) - [Guides](https://developer-beta.morningstar.com/api-guides) - [Trial Access](https://developer-beta.morningstar.com/trial-access) # Investment List API Build the Investment List API into your digital experience for quick investment and earnings summaries. # Example Lists [View Markdown](https://developer-beta.morningstar.com/investment-list-api/example-lists.md)[Download Markdown](https://developer-beta.morningstar.com/investment-list-api/example-lists.md) 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](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list). ## [Before You Use the Examples](#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](https://developer-beta.morningstar.com/investment-list-api/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. ```bash 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](#examples-at-a-glance) | Example | What It Returns | | :------------------------------------- | :--------------------------------------------------------------------- | | Performance Watchlist | Identifiers and returns over several periods. | | Diversification and Exposure Watchlist | Asset allocation, regional, market capitalization and sector exposure. | | Risk and Volatility Watchlist | Standard deviation and risk statistics. | | Equity Valuation Watchlist | Prices, multiples, enterprise value and fair value. | | Fund Due Diligence Watchlist | Fund attributes, fees, size, manager and returns. | | Mix Identifier Types | Several identifier types, with lookup details. | | Sort by Two Data Points | A primary and a secondary sort. | ## [Performance Watchlist](#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. ```json { "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](#diversification-and-exposure-watchlist) Return the category, asset allocation, regional exposure, market capitalization and sector exposure for two funds, identified by ISIN. ```json { "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](#risk-and-volatility-watchlist) Return standard deviation and risk statistics, such as beta, Sharpe ratio and capture ratios, for two investments identified by ISIN. ```json { "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](#equity-valuation-watchlist) Return the latest price, price multiples, enterprise value measures and the quantitative fair value for two equities identified by ISIN. ```json { "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](#fund-due-diligence-watchlist) Return fund attributes, fees, size, manager details and returns for two funds identified by ISIN. ```json { "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](#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. ```json { "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](https://developer-beta.morningstar.com/investment-list-api/work-with-results#match-rows-to-your-request). ## [Sort by Two Data Points](#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. ```json { "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](#next-steps) - [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list) explains each part of a request. - [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results) explains how to read the response and handle warnings. - [Troubleshooting](https://developer-beta.morningstar.com/investment-list-api/troubleshooting) helps when a response isn't what you expected.