openapi: 3.0.1
info:
  version: 1.0.0
  title: Authorization Tokens Accounts Clients 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: Clients
paths:
  /v2/clients/generate-id:
    post:
      tags:
      - Clients
      summary: Create a unique identifier for a client
      description: A client ID is required when submitting a client’s questionnaire responses and when retrieving reports for a specific client. To create a client ID, pass an external identifier (e.g., a client’s email address) in the body of the request. The response will return a unique identifier for the client, which can then be used for future interactions.
      operationId: generateClientId
      parameters:
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateIdRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseGuidPayload'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
      x-codegen-request-body-name: generateClientIdRequest
  /v2/clients/risks/questionnaires:
    post:
      tags:
      - Clients
      summary: Submit a client's risk tolerance questionnaire responses
      description: Submit a client’s risk tolerance questionnaire responses. A risk tolerance score and a unique identifier for the submitted responses is returnd. The identifier can be used to retrieve the client's responses at a later date.
      operationId: submitRiskQuestionnaireResponse
      parameters:
      - name: Accept-Language
        in: header
        description: Specifies the locale.
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-AU
          - en-GB
          - en-IN
          - fr-CA
        example: en-US
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      requestBody:
        description: Payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionnaireRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseAndScorePayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
      x-codegen-request-body-name: questionnaireAnswers
    get:
      tags:
      - Clients
      summary: Get Risk Tolerance questionnaire response history
      description: 'Retrieve a lsit of a client''s previously submitted risk questionnaire responses. A unique identifier for each response is returned. Use the identifier to retrieve a specific response.

        '
      operationId: getRiskQuestionnaireResponseHistory
      parameters:
      - name: clientId
        in: query
        description: Unique identifier of a client
        required: true
        schema:
          type: string
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoryPayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
  /v1/clients/risks/questionnaires/{id}/agreed-score:
    patch:
      tags:
      - Clients
      summary: Submit an agreed risk tolerance score
      description: Submit an agreed risk tolerance score for a specific set of risk tolerance questionnaire responses submitted by a client. **Important:** We recommend that financial professionals resolve any differences (or inconsistencies) in answers in the risk tolerance report with the client through discussion and adjusting the score where appropriate. This discussion and the agreed score should be documented and signed off by the client. The agreed score will be used for further analysis.
      operationId: submitRiskQuestionnaireAgreedScore
      parameters:
      - name: id
        in: path
        description: Unique identifier of a response to a questionnaire
        required: true
        schema:
          type: string
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      requestBody:
        description: Payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgreedRPRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgreedRPPayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
      x-codegen-request-body-name: agreedRPRequest
  /v2/clients/solutions/calculate-suitability-score:
    post:
      tags:
      - Clients
      summary: Calculate suitability score
      description: Using the Professional Judgment Matrix (PJM) framework, calculates the suitability score and score constraints of an investment/portfolio.
      operationId: calculateSuitabilityScore
      parameters:
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: Specifies the locale.
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-AU
          - en-GB
          - en-IN
          - fr-CA
        example: en-US
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateSuitabilityScoreRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateSuitabilityScoreResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
      x-codegen-request-body-name: calculateSuitabilityScoreRequest
  /v1/clients/experience/questionnaires:
    post:
      tags:
      - Clients
      summary: Submit a client's Experience questionnaire responses
      description: 'Submit a client’s experience questionnaire responses. A unique identifier for the submitted responses is returned. The identifier can be used to retrieve the client''s responses at a later date.

        '
      operationId: submitExperienceQuestionnaireResponse
      parameters:
      - name: Accept-Language
        in: header
        description: Specifies the locale.
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-AU
          - en-GB
          - en-IN
          - fr-CA
        example: en-US
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      requestBody:
        description: Payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionnaireRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseGuidPayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
      x-codegen-request-body-name: questionnaireAnswers
    get:
      tags:
      - Clients
      summary: Get Experience questionnaire response history
      description: Get questionnaire responses for the client identified by the value in the `clientId` parameter. You can retrieve a list of all the respones the client has given to past questionnaires.
      operationId: getExperienceQuestionnaireResponseHistory
      parameters:
      - name: clientId
        in: query
        description: Unique identifier of a client
        required: true
        schema:
          type: string
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoryPayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
  /v1/clients/experience/questionnaires/{id}:
    get:
      tags:
      - Clients
      summary: Get Experience response
      description: Get a specific Experience questionnaire response for the client identified by the value in the `clientId` parameter. The questionnaire is identified by the value in the `id` parameter. This ID was returned in the response when the questionnaire was submitted.
      operationId: getExperienceQuestionnaireResponse
      parameters:
      - name: clientId
        in: query
        description: Unique identifier of a client
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of a response to a questionnaire
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: Specifies the locale.
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-AU
          - en-GB
          - en-IN
          - fr-CA
        example: en-US
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAnswerResponsePayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
  /v1/clients/kyc/questionnaires:
    post:
      tags:
      - Clients
      summary: Submit Know Your Client response
      description: 'Submit a client’s know-your-client questionnaire responses. A unique identifier for the submitted responses is returned. The identifier can be used to retrieve the client''s responses at a later date.

        '
      operationId: submitKycQuestionnaireResponse
      parameters:
      - name: Accept-Language
        in: header
        description: Specifies the locale.
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-AU
          - en-GB
          - en-IN
          - fr-CA
        example: en-US
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      requestBody:
        description: Payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionnaireRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseGuidPayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
      x-codegen-request-body-name: questionnaireAnswers
    get:
      tags:
      - Clients
      summary: Get Know Your Client response history
      description: Get Know Your Client questionnaire responses for the client identified by the value in the `clientId` parameter. You can retrieve a list of all the respones the client has given to past questionnaires.
      operationId: getKycQuestionnaireResponseHistory
      parameters:
      - name: clientId
        in: query
        description: Unique identifier of a client
        required: true
        schema:
          type: string
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoryPayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
  /v1/clients/kyc/questionnaires/{id}:
    get:
      tags:
      - Clients
      summary: Get Know Your Client response
      description: Get a specific Know Your Client questionnaire response for the client identified by the value in the `clientId` parameter. The questionnaire is identified by the value in the `id` parameter. This ID was returned in the response when the questionnaire was submitted.
      operationId: getKycQuestionnaireResponse
      parameters:
      - name: clientId
        in: query
        description: Unique identifier of a client
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of a response to a questionnaire
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: Specifies the locale.
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-AU
          - en-GB
          - en-IN
          - fr-CA
        example: en-US
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAnswerResponsePayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
  /v2/clients/risks/reports/{id}:
    get:
      tags:
      - Clients
      summary: Get a specific risk tolerance report for a client
      description: Get a client’s risk tolerance report based on the most recently submitted responses to the risk tolerance questionnaire.
      operationId: getRiskReport
      parameters:
      - name: id
        in: path
        description: Unique identifier of a response to a questionnaire
        required: true
        schema:
          type: string
      - name: clientId
        in: query
        description: Unique identifier of a client
        required: true
        schema:
          type: string
      - name: ignoreSections
        in: query
        example:
        - YOUR_DIFFERENCES
        - FOOTNOTES
        description: Determines the sections NOT to include in the report.If not specified, all the sections will be included. Multiple valuses must be comma-separated.
        schema:
          type: array
          items:
            type: string
      - name: Accept-Language
        in: header
        description: Specifies the locale.
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-AU
          - en-GB
          - en-IN
          - fr-CA
        example: en-US
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponsePayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
  /clients/generate-id:
    post:
      summary: Create unique identifier for a client
      description: Create a unique identifier for a client. You use this alphanumeric ID to identify your client within FinaMetrica. You must include the ID when submitting and retrieving a client's responses. The ID is generated based on the `externalId` (for example, client's email address) that is sent in the request. If your client already has an ID, you do not need to generate a new one. The ID will never expire.
      tags:
      - Clients
      operationId: generateClientId
      parameters:
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        example: 436c05d4-27b6-4a92-b7f1-5a829d55373a
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer access token authorization
        required: true
        schema:
          type: string
      requestBody:
        description: Payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateIdRequest_2'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseGuidPayload'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
  /clients/risks/questionnaires:
    post:
      summary: Submit risk tolerance response
      description: Submit a client’s responses to the risk tolerance questionnaire and return a risk tolerance score. In the response, a unique identifier for the questionnaire will be returned. The identifier can be used to retrieve the answers at any time in the future.
      tags:
      - Clients
      operationId: submitRiskQuestionnaireResponse
      parameters:
      - name: Accept-Language
        in: header
        description: Indicate the locale for the request. e.g. en-US, fr-CA
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-GB
          - en-AU
          - en-IN
          - fr-CA
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        example: 436c05d4-27b6-4a92-b7f1-5a829d55373a
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer access token authorization
        required: true
        schema:
          type: string
      requestBody:
        description: Payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionnaireRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseAndScorePayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
    get:
      summary: Get risk tolerance responses history
      description: Get questionnaire responses for the client identified by the value in the `clientId` parameter. You can retrieve a list of all the responses the client has given to past questionnaires.
      tags:
      - Clients
      operationId: getRiskQuestionnaireResponseHistory
      parameters:
      - name: clientId
        in: query
        description: Unique identifier of a client
        example: 3168dab3-4445-40c5-8295-5a816c6cd5de
        required: true
        schema:
          type: string
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        example: 436c05d4-27b6-4a92-b7f1-5a829d55373a
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer access token authorization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoryPayload_2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
  /clients/risks/questionnaires/{responseId}:
    get:
      tags:
      - Clients
      summary: Get risk tolerance response and score
      description: Get a specific risk questionnaire response and score for the client identified by the value in the `clientId` parameter. The questionnaire is identified by the value in the `id` parameter. This ID was returned in the response when the questionnaire was submitted.
      operationId: getRiskQuestionnaireResponse
      parameters:
      - name: clientId
        in: query
        description: Unique identifier of a client
        example: 3168dab3-4445-40c5-8295-5a816c6cd5de
        required: true
        schema:
          type: string
      - name: responseId
        in: path
        description: Unique identifier of a response to a questionnaire
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: Indicate the locale for the request. e.g. en-US, fr-CA
        required: true
        schema:
          type: string
          enum:
          - en-US
          - en-CA
          - en-GB
          - en-AU
          - en-IN
          - fr-CA
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        example: 436c05d4-27b6-4a92-b7f1-5a829d55373a
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer access token authorization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseAndScorePayload'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '502':
          description: Internal server communication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse502'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
  /clients/risks/questionnaires/{responseId}/agreed-score:
    patch:
      tags:
      - Clients
      summary: Submit risk tolerance agreed score
      description: Submit a client’s agreed score. Before submitting a score, it must be discussed with the client and the client must agree with the score.
      operationId: submitRiskQuestionnaireAgreedScore
      parameters:
      - name: responseId
        in: path
        description: Unique identifier of a response to a questionnaire
        required: true
        schema:
          type: string
      - name: X-API-RequestId
        in: header
        description: Initial request identifier
        example: 436c05d4-27b6-4a92-b7f1-5a829d55373a
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer access token authorization
        required: true
        schema:
          type: string
      requestBody:
        description: Payload
        required: true
        content:
          applica

# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/morningstar/refs/heads/main/openapi/morningstar-clients-api-openapi.yml