Core Concepts

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

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.

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

Each entry in investments identifies one investment. It is an object with an id and, optionally, an idType and lookup details.

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.

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 article for more about lookup.

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 <dataGroup>.<fieldName>, 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.

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.

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 response contains the matching investments and metadata about the response.

{
  "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

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.

Request Limits

For the full list of inputs, see API Inputs.

Next Steps

• Explore Data Points to find the data points you can use.
• Request an Investment List to build a request.
• Work with Results to read the response.
• Example Lists for complete requests you can adapt.