Request an Investment List

An investment list request says which investments you want and which data points to return for each. This page walks through building a complete request, one part at a time. For the ideas behind each part, see Core Concepts.

Request Overview

To retrieve an investment list, send a POST request to the Investment List endpoint.

POST /direct-web-services/v1/investment-list

Use the base URL for your region, as described in Getting Started. The request must include the following headers.

The body is a JSON object. Build it in the following steps.

Step 1: Specify Investments

The investments array lists the investments to retrieve. A request can include from 1 to 100 investments. Each entry is an object with an id, and optionally an idType and lookup details.

The simplest entry is a Morningstar Performance ID, which is the default identifier type.

"investments": [
  { "id": "0P0000004Y" }
]

Use Other Identifier Types

To use another identifier, set idType to say what the id is. The API looks up the matching investment.

You can mix identifier types in one request, with an idType on each entry that needs one.

"investments": [
  { "id": "0P0000004Y" },
  { "id": "US5434957743", "idType": "isin" }
]

Narrow the Lookup

An identifier such as a trading symbol can match more than one investment. Add lookup details to an entry to narrow the match to one.

Each entry has its own lookup details, so the details apply only to the investment in that entry.

"investments": [
  { "id": "IBM", "idType": "tradingSymbol", "exchangeCountry": "USA", "baseCurrency": "USD" }
]

For more about how identifiers are looked up, see the Identifiers article. If an identifier can't be matched, the API returns no row for it, and lists it in metadata.messages. See Work with Results.

Step 2: Select Data Points

The dataPoints array lists the data points to return for each investment. They become the columns of your list.

• Each entry must be a valid data point name, or an alias. See Explore Data Points.
• A request can include up to 50 data points.
• The performance ID is always returned, under the key performanceId.

"dataPoints": [
  "basicReference.fundLegalName",
  "basicReference.isin",
  "morningstarCategory.globalCategory",
  "assetAllocationBreakdown.assetAllocEquityPercNet",
  "trailingReturn.trailing1YearReturn"
]

If a data point name isn't valid, the request fails with an error that lists the invalid names. See Errors.

Step 3: Set Sort Preferences

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 is the secondary key.
• 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.

"sort": [
  { "dataPoint": "trailingReturn.trailing1YearReturn", "orderBy": "desc" },
  { "dataPoint": "basicReference.fundLegalName", "orderBy": "asc" }
]

Each entry needs both a dataPoint and an orderBy. If either is missing, or orderBy isn't asc or desc, the request fails.

Step 4: Set the Language and Currency

The request has two optional properties that set the language and currency of the results.

Send the Request

The following request combines the steps. It retrieves two funds, identified by a performance ID and an ISIN, and sorts them by their one-year return.

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": "0P0000004Y" },
      { "id": "US5434957743", "idType": "isin" }
    ],
    "dataPoints": [
      "basicReference.fundLegalName",
      "basicReference.isin",
      "morningstarCategory.globalCategory",
      "assetAllocationBreakdown.assetAllocEquityPercNet",
      "trailingReturn.trailing1YearReturn"
    ],
    "sort": [
      { "dataPoint": "trailingReturn.trailing1YearReturn", "orderBy": "desc" }
    ]
  }'

The response contains one flat row for each investment that matched, and metadata. See Work with Results.

For more complete requests, see Example Lists.

Request Limits

A request that exceeds a limit fails with a 400 error.

Responses

An error response contains a statusCode, an errorCode, a message and a requestId. In the messages, placeholders such as {0} are replaced with the values from your request. The following validation errors are common.

For the meaning of each error and how to resolve it, see Errors and Troubleshooting.

Next Steps

• Work with Results explains how to read the response and handle warnings.
• Example Lists has complete requests you can adapt.
• API Inputs is a quick reference for every input.