--- title: "FAQs" description: "Answers to common questions about the Investment List API: investments, identifiers, data points, sorting and results." url: "https://developer-beta.morningstar.com/investment-list-api/faqs" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RkFRcyB8IEludmVzdG1lbnQgTGlzdCBBUEk,description_~QW5zd2VycyB0byBjb21tb24gcXVlc3Rpb25zIGFib3V0IHRoZSBJbnZlc3RtZW50IExpc3QgQVBJOiBpbnZlc3RtZW50cywgaWRlbnRpZmllcnMsIGRhdGEgcG9pbnRzLCBzb3J0aW5nIGFuZCByZXN1bHRzLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9pbnZlc3RtZW50LWxpc3QtYXBpL2ZhcXMi,s_EJuxyNIFOfO73cOd.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. # FAQs [View Markdown](https://developer-beta.morningstar.com/investment-list-api/faqs.md)[Download Markdown](https://developer-beta.morningstar.com/investment-list-api/faqs.md) Answers to common questions about the Investment List API. If a request fails or returns unexpected results, see [Troubleshooting](https://developer-beta.morningstar.com/investment-list-api/troubleshooting). ## [General](#general) What does the Investment List API do? It returns tabular, list-based data for up to 100 investments in a single request. It is designed for grid and list views such as watchlists, comparison tables and dashboards, and returns one flat row for each investment, across funds, ETFs and equities. See [Core Concepts](https://developer-beta.morningstar.com/investment-list-api/core-concepts). --- What endpoints does the API have? The API has two endpoints. | Endpoint | Purpose | | :------------------------------------------------------ | :-------------------------------------------------------------------------- | | POST /direct-web-services/v1/investment-list | Returns the investment list for the investments and data points you select. | | GET /direct-web-services/v1/investment-list/data-points | Lists the data points you can use, with their metadata. | Use the base URL for your region. - Americas: `https://www.us-api.morningstar.com` - APAC: `https://www.apac-api.morningstar.com` - EMEA: `https://www.emea-api.morningstar.com` --- Is the API synchronous? Yes. The whole list is returned in the response to the same request. --- Can I use it to find investments that meet criteria? No. The Investment List API returns data for investments that you already know. To find investments that match criteria, use one of the [Screener APIs](https://developer-beta.morningstar.com/screener-apis). For a historical series, use the [Time Series API](https://developer-beta.morningstar.com/time-series-api). --- ## [Authentication](#authentication) How do I authenticate? Request a token from `POST /token/oauth`, then send it on every other request in the `Authorization` header as `Bearer {token}`. See [Authentication](https://developer-beta.morningstar.com/api-authentication). --- How long does an access token last? A token is valid for 60 minutes and can be reused across requests during that time. Long-running jobs must request a new token before it expires, and retry any request that returns `401 Unauthorized`. --- ## [Investments](#investments) How many investments can I request at once? From 1 to 100 per request. To retrieve more, split them across several requests. --- Which identifiers can I use? Morningstar Performance ID (the default), ISIN, fund code, Morningstar Security ID, CUSIP, Morningstar ID and trading symbol. Set `idType` to say which one an `id` is. See [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list#step-1-specify-investments). --- Do I need to set idType? Not for Morningstar Performance IDs, which are the default. For any other identifier, set `idType` on that entry, for example `isin` or `tradingSymbol`. --- Can I mix identifier types in one request? Yes. Each entry has its own `idType`. ```json "investments": [ { "id": "0P0000004Y" }, { "id": "US5434957743", "idType": "isin" } ] ``` --- What if an identifier matches more than one investment? Add lookup details to that entry to narrow the match: `exchangeCountry`, `domicile`, `baseCurrency` or `exchangeId`. Each entry has its own details. See [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list#narrow-the-lookup). --- What happens if an identifier isn't found? The request still succeeds, but no row is returned for that identifier. The identifier is listed in `metadata.messages`. See [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results#identifiers-that-couldnt-be-matched). --- ## [Data Points](#data-points) How do I find valid data point names? Call the data points endpoint. It lists every data point with its name, any alias and its type. See [Explore Data Points](https://developer-beta.morningstar.com/investment-list-api/explore-data-points). --- How many data points can I request? Up to 50 per request. They become the columns of your list. --- Is the performance ID always returned? Yes. Every row has a `performanceId`, whether or not you request it. --- Can I use an alias instead of a name? Yes, where a data point has one. For example, `performanceId` is the alias of `instrumentIdentifiers.performanceId`, and you can use either in `dataPoints`. --- Why is a data point missing from a row? If you aren't entitled to a data point for an investment, 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#handle-warnings). --- ## [Sorting and Results](#sorting-and-results) How do I sort the rows? Use the `sort` array. You can sort by up to 2 data points, applied in order, and each must also be in `dataPoints`. If you don't set a sort order, rows are in ascending performance ID order. See [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list#step-3-set-sort-preferences). --- Are the results paged? No. The rows for all matched investments come back in a single response, up to the 100 investments you asked for. --- How do I match rows to my request? Match on `performanceId`, not on the position of a row, because investments that can't be matched return no row. If you identified investments with something other than a performance ID, add a data point that returns that identifier, such as `basicReference.isin`. See [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results#match-rows-to-your-request). --- Does a 200 response mean every investment returned a row? No. Unmatched identifiers return no row, and data points you aren't entitled to are left out of a row. Both are reported in `metadata.messages`, so always check it. --- What are languageId and currencyId for? They set the language and currency of the results. Both are optional. --- What is the requestId for? It is a unique identifier for the request. It is returned in the response `metadata`, and in error responses. Include it if you contact support. ---