---
title: "Request investment details"
url: "https://developer-beta.morningstar.com/apis/investment-details-feed-api/versions/bc1f8f4b-464c-40a5-af50-a06cce9f3980/operations/postInvestments"
---

> Full API specification: https://developer-beta.morningstar.com/apis/investment-details-feed-api/versions/bc1f8f4b-464c-40a5-af50-a06cce9f3980.md

# Request investment details

`POST` `/direct-web-services/v1/investments`

Operation ID: `postInvestments`

## Header parameters

- `Prefer` (string, required) - Must be set to `respond-async` to indicate the client requires that the request is processed asynchronously. If omitted or set to another value, the server responds with an error message.

## Request body (required)

Content types: `application/json`

## Responses

- `202` - Accepted
- `400` - 400
- `413` - 413
- `500` - 500

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Investment Details Feed API
  version: "1.0"
servers:
  - url: https://www.us-api.morningstar.com
    description: Americas
  - url: https://www.apac-api.morningstar.com
    description: APAC
  - url: https://www.emea-api.morningstar.com
    description: EMEA
paths:
  /direct-web-services/v1/investments:
    post:
      summary: Request investment details
      tags:
        - Investment Details
      parameters:
        - name: Prefer
          in: header
          description: >-
            Must be set to `respond-async` to indicate the client requires that

            the request is processed asynchronously. If omitted or set to
            another value, the server responds with an error message.
          required: true
          schema:
            type: string
            enum:
              - respond-async
      operationId: postInvestments
      requestBody:
        $ref: "#/components/requestBodies/RequestInvestmentDetails"
      responses:
        "202":
          $ref: "#/components/responses/ResponseAccepted"
        "400":
          $ref: "#/components/responses/ResponseBadRequest"
        "413":
          $ref: "#/components/responses/ResponseRequestEntityTooLarge"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"
security:
  - Bearer: []
components:
  requestBodies:
    RequestInvestmentDetails:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RequestInvestmentDetails"
  responses:
    ResponseAccepted:
      description: Accepted
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ResponseAccepted"
    ResponseBadRequest:
      description: "400"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OutputErrorDetails"
    ResponseRequestEntityTooLarge:
      description: "413"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OutputErrorDetails"
    ResponseInternalServerError:
      description: "500"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OutputErrorDetails"
  schemas:
    RequestInvestmentDetails:
      title: RequestInvestmentDetails
      description: Request investment details for up to 3 views and 250 investments.
      type: object
      required:
        - investments
        - views
      properties:
        investments:
          description: List of investments to query.
          type: array
          items:
            $ref: "#/components/schemas/InputInvestment"
          minItems: 1
          maxItems: 250
        views:
          type: array
          description: List of views.
          items:
            $ref: "#/components/schemas/InputView"
          minItems: 1
          maxItems: 3
        startDate:
          type: string
          format: date
          description: Specifies the start date of a time series. Accepts yyyy-MM-dd.
          nullable: true
          example: 2020-01-25
        endDate:
          type: string
          format: date
          description: Specifies the start date of a time series. Accepts yyyy-MM-dd.
          nullable: true
          example: 2024-01-25
        languageId:
          type: string
          description: Specifies the language to filter results on. Required for
            language-dependent data.
          default: ENG
          enum:
            - ENG
            - SPA
            - FRA
            - DEU
            - ITA
            - JPN
            - CHI
            - ZHO
            - KOR
          x-enumDescriptions:
            ENG: English
            SPA: Spanish
            FRA: French
            DEU: German
            ITA: Italian
            JPN: Japanese
            CHI: Chinese Simplified
            ZHO: Chinese Traditional
            KOR: Korean
          nullable: true
        countryId:
          type: string
          description: Specifies the country to filter results on. Accepts 3-character ISO
            3166-1 country codes. Required for country-dependent data.
          default: USA
          example: CAN
          nullable: true
        regionId:
          type: string
          description: Specifies the region for style box breakpoints.
          nullable: true
          example: "1"
          enum:
            - "1"
            - "2"
            - "3"
            - "4"
            - "5"
            - "6"
            - "7"
          x-enumDescriptions:
            "1": United States
            "2": Canada
            "3": Latin America
            "4": Europe
            "5": Japan
            "6": Australia/New Zealand
            "7": Asia excluding Japan
      additionalProperties: false
    ResponseAccepted:
      title: ResponseAccepted
      description: |-
        Defines the HTTP 202 Accepted response returned when a request is
        accepted for asynchronous processing. Includes the job identifier,
        metadata, and links to retrieve the job status or results.
      type: object
      properties:
        jobId:
          type: string
          description: |-
            A unique identifier for the asynchronous job. This ID is used to
            track processing progress or retrieve completed results.
          example: 16bf1a7a-c883-4424-8810-2f4e9d244d40
        _links:
          $ref: "#/components/schemas/OutputResponseLink"
        metadata:
          $ref: "#/components/schemas/OutputMetadata"
    OutputErrorDetails:
      type: object
      properties:
        statusCode:
          type: integer
          description: Status Code
          format: int32
        errorCode:
          type: string
          description: Custom error code
          nullable: true
        message:
          type: string
          description: Message
          nullable: true
        requestId:
          type: string
          description: RequestId
          nullable: true
      additionalProperties: false
      description: Error details
      title: OutputErrorDetails
    InputInvestment:
      title: InputInvestment
      description: Investment to query. Investment look up is supported.
      type: object
      required:
        - id
      additionalProperties: false
      properties:
        id:
          type: string
          description: |-
            Specifies the investment identifier to query. Accepts performance
            IDs, ISINs, security IDs, CUSIPs, trading symbols, and Morningstar
            IDs.
        idType:
          type: string
          example: performanceId
          default: performanceId
          enum:
            - performanceId
            - isin
            - fundCode
            - securityId
            - cusip
            - msid
            - tradingSymbol
            - industryCode
        exchangeCountry:
          type: string
          example: USA
          description: |-
            Specifies exchange country used to look up investment. Accepts
            3-character ISO 3166-1 country codes.
          minLength: 3
          maxLength: 3
        domicile:
          type: string
          example: USA
          description: |-
            Specifies domicile used to look up investment. Accepts 3-character
            ISO 3166-1 country codes.
          minLength: 3
          maxLength: 3
        baseCurrency:
          type: string
          example: USD
          description: |-
            Specifies base currency used to look up investment. Accepts
            3-character ISO 4217 currency codes.
        exchangeId:
          type: string
          example: EX$$$$XNAS
          description: Specifies exchange identifier used to look up investment. See the
            data dictionary for full list of accepted values.
          externalDocs:
            description: Investment Details Equities Data Dictionary (Excel)
            url: https://advisor.morningstar.com/Enterprise/VTC/EquityData/InvestmentDetailsAPIEquityDataDictionary.xlsx
    InputView:
      title: InputView
      type: object
      required:
        - viewId
      properties:
        viewId:
          type: string
          description: The view identifier. Standard view ids are package names; a view
            defined for your organisation uses the identifier issued to you.
        viewType:
          type: string
          default: package
          enum:
            - package
            - DDADataset
    OutputResponseLink:
      title: OutputResponseLink
      type: object
      description: |-
        A set of hypermedia links providing URLs for polling job status or
        accessing results when available.
      properties:
        href:
          type: string
          description: |-
            he fully qualified URL to the related resource or endpoint. Used to
            poll job status or retrieve results.
          example: https://www.us-api.morningstar.com/dynamic-services-apis/jobs/16bf1a7a-c883-4424-8810-2f4e9d244d40
        rel:
          type: string
          description: |-
            Describes the relationship between the current resource and the
            linked resource.
          example: status
        method:
          type: string
          description: The HTTP method to use when invoking the `href` endpoint.
          example: GET
      additionalProperties: false
    OutputMetadata:
      type: object
      properties:
        requestId:
          type: string
          nullable: true
        time:
          type: string
          format: date-time
          readOnly: true
        portfolioDate:
          type: string
          nullable: true
        portfolioCurrency:
          type: string
          nullable: true
        messages:
          type: array
          items:
            $ref: "#/components/schemas/OutputMetadataMessages"
          nullable: true
      additionalProperties: false
      title: OutputMetadata
    OutputMetadataMessages:
      type: object
      properties:
        type:
          type: string
          nullable: true
        code:
          type: string
          nullable: true
        investments:
          type: array
          items:
            $ref: "#/components/schemas/OutputInvalidInvestments"
          nullable: true
        message:
          type: string
          nullable: true
      additionalProperties: false
      title: OutputMetadataMessages
    OutputInvalidInvestments:
      type: object
      properties:
        id:
          type: string
          nullable: true
        idType:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        datapointId:
          type: array
          items:
            type: string
          nullable: true
        errorCode:
          type: string
          nullable: true
        performanceId:
          type: string
          description: Performance ID (if not passed in request).
          nullable: true
        companyId:
          type: string
          description: Company ID (if not passed in request).
          nullable: true
        baseCurrency:
          type: string
          description: Input base currency used to look up Investment identifier
          nullable: true
        domicile:
          type: string
          description: Input domicile used to look up Investment identifier.
          nullable: true
        exchangeCountry:
          type: string
          description: Input exchange country used to look up Investment identifier.
          nullable: true
        exchangeId:
          type: string
          description: Input exchange id used to look up Investment identifier.
          nullable: true
      additionalProperties: false
      title: OutputInvalidInvestments
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "JWT obtained from `POST /token/oauth`. Send it on every request as
        `Authorization: Bearer <token>`. Reuse the token for up to 60 minutes,
        then request a new one."
```