--- title: "Core Concepts" description: "Understand the key ideas behind the Investment List API: investments and lookup, data points, sorting, the flat response and warnings." url: "https://developer-beta.morningstar.com/investment-list-api/core-concepts" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~Q29yZSBDb25jZXB0cyB8IEludmVzdG1lbnQgTGlzdCBBUEk,description_~VW5kZXJzdGFuZCB0aGUga2V5IGlkZWFzIGJlaGluZCB0aGUgSW52ZXN0bWVudCBMaXN0IEFQSTogaW52ZXN0bWVudHMgYW5kIGxvb2t1cCwgZGF0YSBwb2ludHMsIHNvcnRpbmcsIHRoZSBmbGF0IHJlc3BvbnNlIGFuZCB3YXJuaW5ncy4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9pbnZlc3RtZW50LWxpc3QtYXBpL2NvcmUtY29uY2VwdHMi,s_nG0VICdFOUuBu3gx.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. # Core Concepts [View Markdown](https://developer-beta.morningstar.com/investment-list-api/core-concepts.md)[Download Markdown](https://developer-beta.morningstar.com/investment-list-api/core-concepts.md) The Investment List API returns tabular, list-based data for a list of investments in a single request. This page explains the terms used throughout the guide, so that requests and responses are easier to build and read. ## [How an Investment List Works](#how-an-investment-list-works) An investment list is built from a request that names the investments you want and the data points to return for each. The API handles it in this order. 1. It looks up each investment you listed, using its identifier and any lookup details you provide. 2. It retrieves the data points you selected for each investment that it found. 3. It sorts the rows, and returns them in one response as a flat list. A request is made up of the following properties. | Property | Required | Purpose | | :---------- | :------- | :------------------------------------------------------------------------------- | | investments | Yes | The investments to query, from 1 to 100. | | dataPoints | Yes | The data points to return for each investment, up to 50. | | sort | No | The order of the rows, by up to 2 data points. The default is ascending performance ID. | | languageId | No | The language for the results. | | currencyId | No | The currency for the results. | The API has two endpoints. One lists the data points that you can use, with their metadata. The other returns the investment list. Use the first to find out what you can request, and the second to retrieve the data. ## [Investments and Lookup](#investments-and-lookup) Each entry in `investments` identifies one investment. It is an object with an `id` and, optionally, an `idType` and lookup details. | Property | Required | Description | | :-------------- | :------- | :------------------------------------------------------------------------------- | | id | Yes | The investment identifier. | | idType | No | The type of identifier in id. The default is performanceId. | | baseCurrency | No | The base currency used to look up the investment. | | domicile | No | The domicile used to look up the investment, as a 3-character ISO 3166-1 country code. | | exchangeCountry | No | The exchange country used to look up the investment, as a 3-character ISO 3166-1 country code. | | exchangeId | No | The exchange used to look up the investment. | The Morningstar Performance ID is the primary identifier. You can also use the following identifier types, and the API looks up the matching investment for you. | idType | Identifier | | :------------ | :----------------------------------- | | performanceId | Morningstar Performance ID (default) | | isin | ISIN | | fundCode | Fund identifier | | securityId | Morningstar Security ID | | cusip | CUSIP | | msid | Morningstar ID | | tradingSymbol | Trading symbol | An identifier such as a trading symbol can match more than one investment. The lookup details narrow the match, so that each entry resolves to one investment. See the [Identifiers](https://developer-beta.morningstar.com/api-identifiers#identifier-lookup) article for more about lookup. ## [Data Points](#data-points) A data point is a named value for an investment, such as a name, an ISIN, a return or an asset allocation. Data point names have the format `.`, for example `basicReference.name` and `trailingReturn.trailing1YearReturn`. You choose the data points to return with the `dataPoints` array, up to 50 in a request. They become the columns of your list. The data points endpoint describes each data point with metadata. | Metadata | Meaning | | :------- | :------------------------------------------------------------------------------- | | name | The data point name, used in dataPoints and sort. | | alias | An alternative name, where one exists. You can use it in place of the name in a request. | | type | The type of value returned: string, decimal, int or bool. | For example, the data point `instrumentIdentifiers.performanceId` has the alias `performanceId`. The list of data points covers funds, ETFs and equities, so some data points apply to only some types of investment. For how to find the ones you need, see [Explore Data Points](https://developer-beta.morningstar.com/investment-list-api/explore-data-points). ## [Sorting](#sorting) The `sort` array sets the order of the rows. Each entry names a data point and a direction, `asc` or `desc`. - You can sort by up to 2 data points. The first is the primary sort key, and the second breaks ties in the first. - The data point must also be in the `dataPoints` array. - If you don't set a sort order, rows are in ascending performance ID order. ## [The Flat Response](#the-flat-response) The response contains the matching investments and metadata about the response. ```json { "investments": [ { "performanceId": "0P000000YF", "basicReference.name": "CMTSU Liquidation Inc", "basicReference.ticker": "CBRI", "trailingReturn.trailing1YearReturn": "-95.000000" } ], "metadata": { "messages": [ { "investments": [ { "status": "Datapoints are not entitled for 0P000000YF security", "datapointIds": ["reference.currency"], "errorCode": "403", "id": "0P000000YF" } ], "type": "Warning" } ], "requestId": "85b6f9b2-01f9-4da8-90b8-5efb3c1ec31d", "time": "2026-04-13T14:41:48.4913734Z" } } ``` - **Investments.** Each investment is one flat row. Its keys are `performanceId` and the names of the data points you requested, with no nesting. Values are strings or numbers, and can be null. The performance ID is always included. - **No paging.** The rows for all matched investments come back in a single response, up to the 100 you asked for. - **`metadata`.** The `messages`, the `requestId` and the `time`. Include the `requestId` if you contact support. ## [Warnings](#warnings) A `200` response doesn't guarantee that every investment returned every data point. When something couldn't be returned, `metadata.messages` explains why, so check it in every response. It reports two kinds of problem: - **Unmatched identifiers.** If an identifier can't be matched to an investment, the API returns no row for it, and lists the identifier in `messages`, with the details you passed in the request. - **Data points you aren't entitled to.** The investment is still returned without those data points, and `messages` lists the ones that couldn't be returned. Each message has a `type`, which is `Warning`, and a list of the investments it applies to. See [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results). ## [Request Limits](#request-limits) | Limit | Value | | :---------------------- | :------- | | Investments per request | 1 to 100 | | Data points per request | Up to 50 | | Sort fields | Up to 2 | For the full list of inputs, see [API Inputs](https://developer-beta.morningstar.com/investment-list-api/api-inputs). ## [Next Steps](#next-steps) - [Explore Data Points](https://developer-beta.morningstar.com/investment-list-api/explore-data-points) to find the data points you can use. - [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list) to build a request. - [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results) to read the response. - [Example Lists](https://developer-beta.morningstar.com/investment-list-api/example-lists) for complete requests you can adapt.