--- title: "Request an Investment List" description: "Build and send an investment list request: identify investments, select data points, set the sort order, and handle limits and responses." url: "https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~UmVxdWVzdCBhbiBJbnZlc3RtZW50IExpc3QgfCBJbnZlc3RtZW50IExpc3QgQVBJ,description_~QnVpbGQgYW5kIHNlbmQgYW4gaW52ZXN0bWVudCBsaXN0IHJlcXVlc3Q6IGlkZW50aWZ5IGludmVzdG1lbnRzLCBzZWxlY3QgZGF0YSBwb2ludHMsIHNldCB0aGUgc29ydCBvcmRlciwgYW5kIGhhbmRsZSBsaW1pdHMgYW5kIHJlc3BvbnNlcy4,props_eyJ0aGVtZSI6eyJjb2xvcnMiOnt9fX0,p_Ii9pbnZlc3RtZW50LWxpc3QtYXBpL3JlcXVlc3QtYW4taW52ZXN0bWVudC1saXN0Ig,s_1vm4VgLzkR-DvlQz.png" --- # Investment List API Build the Investment List API into your digital experience for quick investment and earnings summaries. # 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](https://developer-beta.morningstar.com/investment-list-api/core-concepts). ## [Request Overview](#request-overview) To retrieve an investment list, send a `POST` request to the Investment List endpoint. ```text POST /direct-web-services/v1/investment-list ``` Use the base URL for your region, as described in [Getting Started](https://developer-beta.morningstar.com/investment-list-api/getting-started). The request must include the following headers. | Header | Value | | :------------ | :---------------------------------- | | Authorization | Bearer {token}. See Authentication. | | Content-Type | application/json | The body is a JSON object. Build it in the following steps. | Step | Property | Purpose | | :--- | :--------------------- | :--------------------------------------------------------------- | | 1 | investments | Identifies the investments to retrieve. Required. | | 2 | dataPoints | Chooses the data points to return for each investment. Required. | | 3 | sort | Sets the order of the rows. | | 4 | languageId, currencyId | Sets the language and currency of the results. | ## [Step 1: Specify Investments](#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. ```json "investments": [ { "id": "0P0000004Y" } ] ``` ### [Use Other Identifier Types](#use-other-identifier-types) To use another identifier, set `idType` to say what the `id` is. The API looks up the matching investment. | idType | Identifier | Example id | | :------------ | :----------------------------------- | :----------- | | performanceId | Morningstar Performance ID (default) | 0P0000004Y | | isin | ISIN | US5434957743 | | fundCode | Fund identifier | FS00008NJG | | securityId | Morningstar Security ID | | | cusip | CUSIP | 868536AT0 | | msid | Morningstar ID | | | tradingSymbol | Trading symbol | IBM | You can mix identifier types in one request, with an `idType` on each entry that needs one. ```json "investments": [ { "id": "0P0000004Y" }, { "id": "US5434957743", "idType": "isin" } ] ``` ### [Narrow the Lookup](#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. | Property | Description | | :-------------- | :-------------------------------------------------------------- | | exchangeCountry | The exchange country, as a 3-character ISO 3166-1 country code. | | domicile | The domicile, as a 3-character ISO 3166-1 country code. | | baseCurrency | The base currency, as a 3-character ISO 4217 currency code. | | exchangeId | The exchange identifier. | Each entry has its own lookup details, so the details apply only to the investment in that entry. ```json "investments": [ { "id": "IBM", "idType": "tradingSymbol", "exchangeCountry": "USA", "baseCurrency": "USD" } ] ``` For more about how identifiers are looked up, see the [Identifiers](https://developer-beta.morningstar.com/api-identifiers#identifier-lookup) 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](https://developer-beta.morningstar.com/investment-list-api/work-with-results). ## [Step 2: Select Data Points](#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](https://developer-beta.morningstar.com/investment-list-api/explore-data-points). - A request can include up to 50 data points. - The performance ID is always returned, under the key `performanceId`. ```json "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](https://developer-beta.morningstar.com/investment-list-api/error-messages). ## [Step 3: Set Sort Preferences](#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. ```json "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](#step-4-set-the-language-and-currency) The request has two optional properties that set the language and currency of the results. | Property | Description | | :--------- | :-------------------------------------------- | | languageId | The language for the investment list results. | | currencyId | The currency for the investment list results. | ## [Send the Request](#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. ```bash 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](https://developer-beta.morningstar.com/investment-list-api/work-with-results). For more complete requests, see [Example Lists](https://developer-beta.morningstar.com/investment-list-api/example-lists). ## [Request Limits](#request-limits) | Limit | Value | | :---------------------- | :------- | | Investments per request | 1 to 100 | | Data points per request | Up to 50 | | Sort fields | Up to 2 | A request that exceeds a limit fails with a `400` error. ## [Responses](#responses) | Status | Description | | :----- | :------------------------------------------------------------------------------- | | 200 | The request succeeded. The body contains the investments rows and a metadata object. Check metadata.messages for warnings. | | 400 | The request is invalid. Read the message to find the problem. | | 401 | Unauthorized. The token is missing, invalid or expired. | | 403 | Forbidden. | | 500 | An internal server error occurred. | 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. | Error Code | Message | | :--------------------- | :------------------------------------------------------------------------------- | | 400.investmentList.002 | The {0} parameter is required. | | 400.investmentList.003 | The number of {0} exceeds limit. Maximum {0} allowed are {1} per request | | 400.investmentList.004 | Invalid datapoints {0}. Please send the datapoint name correctly | | 400.investmentList.005 | Missing Values for sort parameter either DataPoint or OrderBy | | 400.investmentList.006 | Please provide correct values for OrderBy which is 'asc' or 'desc' | | 400.investmentList.007 | Mismatch values of the dataPoint provided in sort. Please verify the dataPoint from the datapoints node in order to sort | For the meaning of each error and how to resolve it, see [Errors](https://developer-beta.morningstar.com/investment-list-api/error-messages) and [Troubleshooting](https://developer-beta.morningstar.com/investment-list-api/troubleshooting). ## [Next Steps](#next-steps) - [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results) explains how to read the response and handle warnings. - [Example Lists](https://developer-beta.morningstar.com/investment-list-api/example-lists) has complete requests you can adapt. - [API Inputs](https://developer-beta.morningstar.com/investment-list-api/api-inputs) is a quick reference for every input.