openapi: 3.0.1
info:
  version: 1.0.0
  title: Authorization Tokens Accounts Consensus Recommendations API
  description: 'Use the `oauth` endpoint to generate the secure, time-limited JSON Web Tokens (JWTs) used to authorize access to APIs and components.</br></br>

    To request a token, click Authorize and enter the following credentials:


    * Username - Your Client ID.

    * Password - Your Client Secret.'
servers:
- url: https://www.us-api.morningstar.com/token
  description: PROD US
- url: https://www.emea-api.morningstar.com/token
  description: PROD EMEA
- url: https://www.apac-api.morningstar.com/token
  description: PROD APAC
security:
- BasicAuth: []
tags:
- name: Consensus Recommendations
paths:
  /direct-web-services/v1/investments/{id}/equity-consensus-recommendations:
    get:
      summary: Get Consensus Recommendations package view
      parameters:
      - name: id
        in: path
        description: "\nSpecifies the investment to query. \nMorningstar Performance ID is the default identifer for the API. Use the Universe API to retrieve Performance IDs for investments in your entitled universe."
        required: true
        schema:
          type: string
          example: 0P00000046
        examples:
          performanceId:
            summary: Morningstar Performance ID
            value: 0P00000046
          isin:
            summary: ISIN
            value: US0042391096
      - name: idType
        in: query
        description: 'Specifies the type of the value passed in the `id` parameter.

          Morningstar Performance ID is the default identifer for the API. Use the Universe API to retrieve Performance IDs for investments in your entitled universe.'
        schema:
          enum:
          - performanceId
          - isin
          - securityId
          - cusip
          - tradingSymbol
          - fundCode
          - msid
          type: string
          default: performanceId
      - name: baseCurrency
        in: query
        description: Base currency to use for investment lookup. Accepts 3‑character ISO 4217 currency codes.
        schema:
          type: string
        examples:
          baseCurrencyExample1:
            summary: US Dollar
            value: USD
          baseCurrencyExample2:
            summary: Swiss Franc
            value: CHF
      - name: domicile
        in: query
        description: Domicile to use for investment lookup. Accepts 3-character ISO 3166-1 country codes.
        schema:
          type: string
        examples:
          domicileExample1:
            summary: CAN (Canada)
            value: CAN
          domicileExample2:
            summary: JPN (Japan)
            value: JPN
          domicileExample3:
            summary: USE (United States)
            value: USA
      - name: exchangeCountry
        in: query
        description: Exchange country to use for investment lookup. Accepts 3-character ISO 3166-1 country codes.
        schema:
          type: string
        examples:
          exchangeCountryExample1:
            summary: CAN (Canada)
            value: CAN
          exchangeCountryExample2:
            summary: JPN (Japan)
            value: JPN
          exchangeCountryExample3:
            summary: USA (USA)
            value: USA
      - name: exchangeId
        in: query
        description: Exchange identifier to use for investment lookup.
        schema:
          type: string
          externalDocs:
            description: List of exchange IDs.
            url: https://developer.morningstar.com/content/hidden-from-navigation/DwsIdLookUpExchangeIds.xlsx
        examples:
          exchangeIdExample1:
            summary: NASDAQ - ALL Markets (NAS)
            value: EX$$$$XNAS
          exchangeIdExample2:
            summary: London Stock Exchange (LSE)
            value: EX$$$$XLON
      - name: startDate
        in: query
        schema:
          type: string
          format: yyyy-MM-dd
        description: Time series start date. Accepts `yyyy-MM-dd`.
        examples:
          startDateExample1:
            summary: Example 1
            value: '2025-06-01'
          startDateExample2:
            summary: Example 2
            value: '2025-06-30'
      - name: endDate
        in: query
        schema:
          type: string
          format: yyyy-MM-dd
        description: Time series end date. Accepts `yyyy-MM-dd`.
        examples:
          endDateExample1:
            summary: Example 1
            value: '2025-12-01'
          endDateExample2:
            summary: Example 2
            value: '2025-12-31'
      description: '


        The Consensus Recommendations package provides an aggregated recommendation calculated from those provided to us from our contributing brokers, along with details of how many brokers provided a recommendation across the range of buy to sell for each stock under coverage.


        Most recent and time series data supported.'
      operationId: getEquityConsensusRecommendationsDataset
      tags:
      - Consensus Recommendations
      responses:
        '200':
          $ref: '#/components/responses/ResponseEquityConsensusRecommendations'
        '400':
          $ref: '#/components/responses/ResponseBadRequest'
        '500':
          $ref: '#/components/responses/ResponseInternalServerError'
      x-cpqId: 919
components:
  schemas:
    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
    OutputConsensusRawRecommendations:
      type: object
      properties:
        asOfDate:
          type: string
          description: Consensus date in numeric format
          nullable: true
        buy:
          type: integer
          description: Number of brokers providing buy recommendation
          format: int32
          nullable: true
        hold:
          type: integer
          description: Number of brokers providing hold recommendation
          format: int32
          nullable: true
        meanLabel:
          type: string
          description: The possible values are NoOpinion - if mean_rating is equal to (=) 0; Sell - if mean_rating is less than equal to (<=) 1.5; Underperform - if mean_rating is less than equal to (<=) 2.5; Hold - if mean_rating is less than equal to (<=) 3.5; Outperform -  if mean_rating is less than equal to (<=) 4.5; Buy -  if mean_rating is greater than (>) 4.5; NoOpinion - if the before conditions is not satisfied
          nullable: true
        meanRating:
          type: number
          description: The is mean rating is considered on the basis of 5 fields; each filed is assigned a default value that is buy(5); out_perform(4); hold(3); under_perform(2); sell(1); each of these default value is multiplied with brokers recommendation and the mean is calculated of the multipied result
          format: double
          nullable: true
        noOpinion:
          type: integer
          description: Number of brokers providing no opinion recommendation
          format: int32
          nullable: true
        outPerform:
          type: integer
          description: Number of brokers providing  outperform recommendation
          format: int32
          nullable: true
        sell:
          type: integer
          description: Number of brokers providing sell recommendation
          format: int32
          nullable: true
        underPerform:
          type: integer
          description: Number of brokers providing under perform recommendation
          format: int32
          nullable: true
      additionalProperties: false
      title: OutputConsensusRawRecommendations
    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
    OutputIdentifiers:
      type: object
      properties:
        performanceId:
          type: string
          nullable: true
        securityId:
          type: string
          nullable: true
        cusip:
          type: string
          nullable: true
        isin:
          type: string
          nullable: true
        sedol:
          type: string
          nullable: true
        tradingSymbol:
          type: string
          nullable: true
        fundCode:
          type: string
          nullable: true
        msid:
          type: string
          nullable: true
        ticker:
          type: string
          nullable: true
      additionalProperties: false
      title: OutputIdentifiers
    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
    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
  responses:
    ResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OutputErrorDetails'
    ResponseInternalServerError:
      description: Internal Server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OutputErrorDetails'
    ResponseEquityConsensusRecommendations:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              consensusRawRecommendations:
                $ref: '#/components/schemas/OutputConsensusRawRecommendations'
              identifiers:
                $ref: '#/components/schemas/OutputIdentifiers'
              metadata:
                $ref: '#/components/schemas/OutputMetadata'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic