The token is missing, invalid or expired.

• Check that the Authorization header is present and uses the format Bearer {token}.
• Tokens expire after 60 minutes. Request a new token from POST /token/oauth, then retry the request.
• In long-running jobs, refresh the token before it expires, and retry any request that returns 401 after refreshing.

See Authentication.

The request was authenticated but access was refused. Confirm that your account is licensed for the Investment List API. Your Morningstar account manager can confirm what your agreement includes.

An error occurred on the server, for example Error calling Investment Service Api. Error details are not included in the response. Check that the request body is valid JSON, then retry the request. If the error persists, contact Morningstar support with the requestId and the time of the request.

The request is invalid. The message in the response describes the problem.

• Read the message and errorCode, then find the property it names.
• Check the properties against the API Inputs reference.
• If you can't find the cause, contact support and include the requestId.

The response says The {0} parameter is required and gives the error code 400.investmentList.002. The message names the missing parameter, for example Investments.

• Check that the body includes both investments and dataPoints.
• Check the spelling and capitalization of the property names, and that each is an array.

The response says The number of {0} exceeds limit and gives the error code 400.investmentList.003. The message names the limit that was exceeded.

• A request can include from 1 to 100 investments. Split larger lists across several requests.
• A request can include up to 50 data points. If you need more columns, make several requests and join the rows on performanceId.
• A request can include up to 2 sort fields.

See Request an Investment List.

The response says Invalid datapoints and gives the error code 400.investmentList.004. The message lists the names that weren't accepted.

• Check each name in dataPoints for typos. Names have the format dataGroup.fieldName, so a bare field name such as legalName isn't valid.
• Retrieve the valid names from the data points endpoint, and copy them from there. See Explore Data Points.

Sort errors have three causes.

• Missing values (400.investmentList.005). Each sort entry needs both a dataPoint and an orderBy.
• Invalid direction (400.investmentList.006). orderBy must be asc or desc.
• Mismatched data point (400.investmentList.007). The dataPoint in sort must also be in the dataPoints array. Add it to dataPoints, or sort by a data point you are already requesting.

See Request an Investment List.

The response gives the error code 400.investmentList.009 or 400.investmentList.010, and says to provide the request input in valid JSON.

• Check for missing commas, unclosed brackets and braces, and trailing commas.
• Check that keys and string values use double quotation marks.
• Check that numbers and booleans have no quotation marks.
• Check that Content-Type is application/json. A JSON validator can help to find the problem.

The response gives the error code 400.investmentList.008 and says that an IdType isn't supported.

• Set idType to one of performanceId, isin, fundCode, securityId, cusip, msid or tradingSymbol, spelled exactly as shown.
• Check that each idType matches the identifier in its id.

See Request an Investment List.

The request succeeded but one of your investments has no row. Unmatched identifiers are listed in metadata.messages, and the investments array contains only the investments that matched.

1. Check metadata.messages for the identifier and its idType.
2. Check the identifier for typos.
3. Check that idType matches the identifier. An entry with no idType is treated as a Morningstar Performance ID.
4. Check whether lookup details, such as domicile or exchangeCountry, are excluding the investment.
5. Try a different identifier for the same investment. The Morningstar Performance ID is the most precise.

See Work with Results.

An identifier such as a trading symbol can match more than one investment.

• Add lookup details to the entry, such as exchangeCountry, domicile, baseCurrency or exchangeId, to narrow the match.
• Use a Performance ID, which identifies a single investment.
• Add a data point such as basicReference.name or instrumentIdentifiers.isin to the request, to check which investment each row is for.

See Request an Investment List.

The row was returned, but a data point you requested isn't in it.

• Check metadata.messages. If you aren't entitled to the data point, a warning lists it, with the error code 403.
• Remove data points that you aren't entitled to from dataPoints, or contact your Morningstar account manager about access.

See Work with Results.

The rows don't repeat the identifiers you sent, and an investment that can't be matched has no row.

• Match rows using performanceId, not the position of the row.
• If you sent ISINs, trading symbols or other identifiers, add a data point that returns that identifier, for example basicReference.isin or instrumentIdentifiers.isin.
• Check metadata.messages for identifiers that returned no row.

See Work with Results.

• If you don't set sort, rows are in ascending performance ID order.
• sort entries are applied in order, so put the most important sort first. You can use at most 2.
• Check that orderBy is asc or desc. The default is asc.
• The sorted data point must also be in dataPoints.

Some numeric values can be returned as strings, for example "-95.000000". Convert them to numbers in your application before you calculate with them or sort them.

A missing value is returned as null, or the data point is left out of the row. Handle both.

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

• Check that you set them, and that the values are accepted. See API Inputs.
• Check whether the data point you are reading depends on a language or a currency.