Real-time Transactions Output Specification — YAML

A Transaction is the output from the Morningstar® Retirement ManagerSM application and contains Advice information. It may include details about Reallocations, Future Elections, and Contributions depending on Recordkeeper specific configuration on our side. When a participant interacts with the Morningstar® Retirement ManagerSM website and chooses to either receive one-time Advice or enroll in the full Managed Accounts offering, a transaction payload is generated and sent to the client via an HTTP request.

Real-time Transactions

Morningstar uses the data collected from the Recordkeeper (in the Plan Batch and Participant Real-time XML Files) and the web application to generate recommendations for participants should they choose to enroll in our service offering. These recommendations are sent in the form of a ‘Transaction’. The transaction is sent when the user enrolls in a plan supported Service Option using the Morningstar® Retirement ManagerSM web application. The Transaction includes instructions for realigning current balances, setting future contributions, and adjusting contribution rates. The client receives our transaction request, parses the fund identifiers, percentages, and contribution rates included in our transaction, and implements the instructions.

Transaction Request

HTTP Method: POST
Request Body: JSON formatted string
Content-Type Header: “application/json”
Accept Header: “application/json”
Request URL: See details below;

The transaction is sent from the RM web application as a JSON formatted payload in an HTTP Post request with Content-Type header value of “application/json”. The transaction payload will be an instance of type “Transaction” as detailed in the Morningstar® Retirement ManagerSM transaction schema specification (OpenAPI v3 API specification) shared with the client and included below.

Transaction schema specification in YAML format:

openapi: 3.0.1
info:
  title: Retirement Manager Integration API
  description: Customer-hosted Retirement Manager integration API specification
  version: 2.63.0.0
servers:
- url: https://api.customer.com/transaction
paths:
  /Transaction:
    post:
      tags:
      - Transaction
      operationId: Transaction_ExecuteTransaction
      requestBody:
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Transaction'
          text/xml:
            schema:
              $ref: '#/components/schemas/Transaction'
          application/json:
            schema:
              $ref: '#/components/schemas/Transaction'
          text/json:
            schema:
              $ref: '#/components/schemas/Transaction'
        required: true
      responses:
        200:
          description: ""
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/TransactionExecutionResponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/TransactionExecutionResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionExecutionResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/TransactionExecutionResponse'
      security:
      - Bearer: []
      - apiKey: []
      x-codegen-request-body-name: transaction
components:
  schemas:
    TransactionExecutionResponse:
      required:
      - success
      type: object
      properties:
        success:
          type: boolean
        confirmationIdentifier:
          type: string
          maximum: 100
          minimum: 1
        confirmInformation:
          type: string
          maximum: 4096
          minimum: 0
    Transaction:
      required:
      - timeStamp
      - clientID
      type: object
      properties:
        userTransaction:
          type: array
          items:
            $ref: '#/components/schemas/UserTransactionType'
          description: Each user transaction instance may contain multiple accounts
        timeStamp:
          type: string
          format: date-time
        clientID:
          type: string
      description: Describe one or more transactions, this format is used for both real-time, single user, offline batch and multiple user transactions
    UserTransactionType:
      required:
      - trackingID
      - userID
      - firstName
      - lastName
      type: object
      properties:
        account:
          type: array
          description: Each account is mapped to one institutional plan. Plan ID and Type must be set at Account level
          items:
            $ref: '#/components/schemas/AccountType'
        communicationXml:
          type: string
          maximum: 1
          minimum: 0
        trackingID:
          type: string
          description: Used for transaction reconciliation
        userID:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        phoneRepID:
          type: string
        hasGMWBAdjustment:
          type: boolean
        timeStamp:
          type: string
        sessionToken:
          type: string
          maximum: 16000
          minimum: 1
    AccountType:
      required:
      - planID
      - serviceOption
      - status
      - type
      type: object
      properties:
        pretaxContriRate:
          type: array
          maximum: 2
          minimum: 0
          items:
            $ref: '#/components/schemas/ContriRateSourceType'
        rothContriRate:
          type: array
          maximum: 2
          minimum: 0
          items:
            $ref: '#/components/schemas/ContriRateSourceType'
        posttaxContriRate:
          type: array
          maximum: 2
          minimum: 0
          items:
            $ref: '#/components/schemas/ContriRateSourceType'
        catchup50Years:
          type: array
          maximum: 4
          minimum: 0
          items:
            $ref: '#/components/schemas/TxnCatchupType'
        catchupLongTerm:
          type: array
          maximum: 4
          minimum: 0
          items:
            $ref: '#/components/schemas/TxnCatchupType'
        catchupLast3Years:
          type: array
          maximum: 4
          minimum: 0
          items:
            $ref: '#/components/schemas/TxnCatchupType'
        brkg:
          type: object
        csTarget:
          $ref: '#/components/schemas/AccountTypeCSTarget'
          minimum: 0
        reallocation:
          type: array
          items:
            $ref: '#/components/schemas/SecurityListTypeSecurity'
        futureElection:
          type: array
          items:
            $ref: '#/components/schemas/SecurityListTypeSecurity'
        planID:
          type: string
        serviceOption:
          $ref: '#/components/schemas/ServiceOptionType'
        type:
          $ref: '#/components/schemas/PlanType'
        tpaid:
          type: string
        optOutUpdate:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/StatusType'
        transactionRoutingID:
          type: string
          description: TransactionRoutingID is for the client to send us data that they need back in the transaction file.
        contriFrequency:
          $ref: '#/components/schemas/FrequencyType'
    ContriRateSourceType:
      allOf:
      - $ref: '#/components/schemas/ContriRateType'
      type: object
      properties:
        contriSource:
          type: object
          allOf:
          - $ref: '#/components/schemas/ContriSourceType'
    ContriSourceType:
      type: string
      enum:
      - Basic
      - Supplemental
      x-enumNames:
      - Basic
      - Supplemental
    ContriRateType:
      required:
      - amount
      - rate
      type: object
      properties:
        rate:
          type: number
          format: decimal
          maximum: 100
          minimum: 0
        amount:
          type: number
          format: decimal
          maximum: 99999999
          minimum: 0
        deferralFormatType:
          $ref: '#/components/schemas/DeferralFormatType'
    DeferralFormatType:
      type: string
      enum:
      - Rate
      - Amount
      - RateOrAmount
      x-enumNames:
      - Rate
      - Amount
      - RateOrAmount
    TxnCatchupType:
      allOf:
      - $ref: '#/components/schemas/ContriRateType'
      type: object
      properties:
        roth:
          type: boolean
        catchupYear:
          $ref: '#/components/schemas/CatchupYearType'
    CatchupYearType:
      type: string
      enum:
      - Current
      - Future
      x-enumNames:
      - Current
      - Future
    AccountTypeCSTarget:
      type: object
      properties:
        cs:
          type: array
          items:
            $ref: '#/components/schemas/AccountTypeCSTargetCS'
      maximum: 10
      minimum: 0
    AccountTypeCSTargetCS:
      required:
      - id
      - target
      type: object
      properties:
        id:
          type: string
        target:
          type: number
          format: decimal
    SecurityListTypeSecurity:
      required:
      - transactionID
      - isCS
      - perc
      type: object
      properties:
        transactionID:
          type: string
        perc:
          type: number
          format: decimal
          maximum: 100
          minimum: 0
        isCS:
          type: boolean
    ServiceOptionType:
      type: string
      enum:
      - NONE
      - QuantMRP
      - QualMRP
      - OnlineAdvice
      - OnlineCallCenter
      - Statement
      - OfferLetter
      - InRetirement
      - OnlineGuidance
      - NoMatch
      - Proposal
      - RID
      - PortfolioModels
      - PlanSponsorAdvice
      - AssetAllocModels
      - CustomModels
      - RK
      - Direct
      x-enumNames:
      - NONE
      - QuantMRP
      - QualMRP
      - OnlineAdvice
      - OnlineCallCenter
      - Statement
      - OfferLetter
      - InRetirement
      - OnlineGuidance
      - NoMatch
      - Proposal
      - RID
      - PortfolioModels
      - PlanSponsorAdvice
      - AssetAllocModels
      - CustomModels
      - RK
      - Direct
    PlanType:
      type: string
      enum:
      - 401K
      - Thrift
      - ProfitSharing
      - MoneyPurchase
      - 403B
      - Sup403B
      - 457B
      - 457F
      - 401A
      - TradIRA
      - RothIRA
      - PosttaxIRA
      - RetirementPlansfromPrevEmp
      - Variable Annuities
      - TaxableAccount
      - CompanyStockHeldOutsideYourRetirementPlan
      - OtherPensionPlans
      - CashfromSellingHouse
      - RolloverIRA
      - SEP_IRA
      - StockOptionsSets
      - Keogh
      - EduIRA
      - Edu529
      - BenchmarkModel
      - TaxDeferred
      - Cash
      - NonQual
      - TaftHartley
      - NonQualifiedVA
      - HighlyCompAcct
      - SIMPLE_IRA
      - NonAdvisable
      - ESOP
      - CashBalance
      x-enumNames:
      - Item401K
      - Thrift
      - ProfitSharing
      - MoneyPurchase
      - Item403B
      - Sup403B
      - Item457B
      - Item457F
      - Item401A
      - TradIRA
      - RothIRA
      - PosttaxIRA
      - RetirementPlansfromPrevEmp
      - VariableAnnuities
      - TaxableAccount
      - CompanyStockHeldOutsideYourRetirementPlan
      - OtherPensionPlans
      - CashfromSellingHouse
      - RolloverIRA
      - SEP_IRA
      - StockOptionsSets
      - Keogh
      - EduIRA
      - Edu529
      - BenchmarkModel
      - TaxDeferred
      - Cash
      - NonQual
      - TaftHartley
      - NonQualifiedVA
      - HighlyCompAcct
      - SIMPLE_IRA
      - NonAdvisable
      - ESOP
      - CashBalance
    StatusType:
      type: string
      enum:
      - Active
      - Eligible
      - Suspended
      - Termed
      - Inactive
      - ""
      x-enumNames:
      - Active
      - Eligible
      - Suspended
      - Termed
      - Inactive
      - Item
    FrequencyType:
      type: string
      enum:
      - OneTime
      - Annual
      - SemiAnnual
      - Quarterly
      - Monthly
      - SemiMonthly
      - BiWeekly
      - Weekly
      - Hourly
      x-enumNames:
      - OneTime
      - Annual
      - SemiAnnual
      - Quarterly
      - Monthly
      - SemiMonthly
      - BiWeekly
      - Weekly
      - Hourly
  securitySchemes:
    Bearer:
      type: oauth2
      description: Bearer
      flows:
        clientCredentials:
          tokenUrl: https://api.customer.com/oauth2/access_token
          scopes: {}
    apiKey:
      type: apiKey
      description: apiKey
      name: apiKey
      in: header
x-generator: NSwag v13.1.3.0 (NJsonSchema v10.0.27.0 (Newtonsoft.Json v12.0.0.0))


Transaction schema specification in JSON format:


An Example of Non-Integrated – QUALMRP:

{
  "Transaction": {
    "TimeStamp": "2025-07-22T00:03:17.0843746-05:00",
    "ClientID": "TRPX",
    "UserTransaction": {
      "TrackingID": "963339ff-2b6b-45bb-bc7d-2b0c01e9e3e7",
      "UserID": "20250721-TRPX-ineom",
      "FirstName": "ScrubbedFirstName",
      "LastName": "ScrubbedLastName",
      "TimeStamp": "2025-07-22T00:03:17",
      "Account": {
        "PlanID": "105537",
        "ServiceOption": "QualMRP",
        "Type": "401K",
        "Status": "Active",
        "PretaxContriRate": {
          "Rate": "7",
          "Amount": "7525"
        },
        "RothContriRate": {
          "Rate": "0",
          "Amount": "0"
        },
        "PosttaxContriRate": {
          "Rate": "0",
          "Amount": "0"
        },
        "Reallocation": {
          "Security": [
            { "TransactionID": "DFISX", "Perc": "15", "IsCS": "false" },
            { "TransactionID": "SCS", "Perc": "10", "IsCS": "false" },
            { "TransactionID": "STB", "Perc": "11", "IsCS": "false" },
            { "TransactionID": "RNWFX", "Perc": "5", "IsCS": "false" },
            { "TransactionID": "RWMFX", "Perc": "8", "IsCS": "false" },
            { "TransactionID": "VASVX", "Perc": "13", "IsCS": "false" },
            { "TransactionID": "VBTIX", "Perc": "7", "IsCS": "false" },
            { "TransactionID": "VFTSX", "Perc": "31", "IsCS": "false" }
          ]
        },
        "FutureElection": {
          "Security": [
            { "TransactionID": "DFISX", "Perc": "15", "IsCS": "false" },
            { "TransactionID": "SCS", "Perc": "10", "IsCS": "false" },
            { "TransactionID": "STB", "Perc": "11", "IsCS": "false" },
            { "TransactionID": "RNWFX", "Perc": "5", "IsCS": "false" },
            { "TransactionID": "RWMFX", "Perc": "8", "IsCS": "false" },
            { "TransactionID": "VASVX", "Perc": "13", "IsCS": "false" },
            { "TransactionID": "VBTIX", "Perc": "7", "IsCS": "false" },
            { "TransactionID": "VFTSX", "Perc": "31", "IsCS": "false" }
          ]
        }
      }
    }
  }
}

An Example of Opt-Out / Cancel:

{
  "Transaction": {
    "TimeStamp": "2025-07-22T00:14:17.7351672-05:00",
    "ClientID": "TRPX",
    "UserTransaction": {
      "TrackingID": "4197a3fb-b499-44ad-8495-3667899383d1",
      "UserID": "20250721-TRPX-ineom",
      "FirstName": "ScrubbedFirstName",
      "LastName": "ScrubbedLastName",
      "TimeStamp": "2025-07-22T00:14:17",
      "Account": {
        "PlanID": "105537",
        "ServiceOption": "NONE",
        "Type": "401K",
        "Status": "Active"
      }
    }
  }
}

An Example of OnlineAdvice:

{
  "Transaction": {
    "TimeStamp": "2025-07-22T00:19:31.153786-05:00",
    "ClientID": "TRPX",
    "UserTransaction": {
      "TrackingID": "eed856c9-adc8-4f74-8a9f-b0604a3ab7a4",
      "UserID": "20250721-TRPX-miymj",
      "FirstName": "ScrubbedFirstName",
      "LastName": "ScrubbedLastName",
      "TimeStamp": "2025-07-22T00:19:31",
      "Account": {
        "PlanID": "105537",
        "ServiceOption": "OnlineAdvice",
        "Type": "401K",
        "Status": "Active",
        "PretaxContriRate": {
          "Rate": "7",
          "Amount": "7525"
        },
        "RothContriRate": {
          "Rate": "0",
          "Amount": "0"
        },
        "PosttaxContriRate": {
          "Rate": "0",
          "Amount": "0"
        },
        "Reallocation": {
          "Security": [
            { "TransactionID": "DFISX", "Perc": "15", "IsCS": "false" },
            { "TransactionID": "SCS", "Perc": "10", "IsCS": "false" },
            { "TransactionID": "STB", "Perc": "11", "IsCS": "false" },
            { "TransactionID": "RNWFX", "Perc": "5", "IsCS": "false" },
            { "TransactionID": "RWMFX", "Perc": "8", "IsCS": "false" },
            { "TransactionID": "VASVX", "Perc": "13", "IsCS": "false" },
            { "TransactionID": "VBTIX", "Perc": "7", "IsCS": "false" },
            { "TransactionID": "VFTSX", "Perc": "31", "IsCS": "false" }
          ]
        },
        "FutureElection": {
          "Security": [
            { "TransactionID": "DFISX", "Perc": "15", "IsCS": "false" },
            { "TransactionID": "SCS", "Perc": "10", "IsCS": "false" },
            { "TransactionID": "STB", "Perc": "11", "IsCS": "false" },
            { "TransactionID": "RNWFX", "Perc": "5", "IsCS": "false" },
            { "TransactionID": "RWMFX", "Perc": "8", "IsCS": "false" },
            { "TransactionID": "VASVX", "Perc": "13", "IsCS": "false" },
            { "TransactionID": "VBTIX", "Perc": "7", "IsCS": "false" },
            { "TransactionID": "VFTSX", "Perc": "31", "IsCS": "false" }
          ]
        }
      }
    }
  }
}

An Example of Integrated – QUALMRP (2 Plans):

{
  "Transaction": {
    "TimeStamp": "2025-07-22T00:38:53.9747813-05:00",
    "ClientID": "ICMARC",
    "UserTransaction": {
      "TrackingID": "b0f98af3-5db5-4665-b22c-7b19c74a5e80",
      "UserID": "20250721-ICMARC-4qadc",
      "FirstName": "JERISE",
      "LastName": "MARGULIES",
      "TimeStamp": "2025-07-22T00:38:53",
      "Account": [
        {
          "PlanID": "100045",
          "ServiceOption": "QualMRP",
          "Type": "401K",
          "Status": "Active",
          "TransactionRoutingID": "DAILY",
          "Reallocation": {
            "Security": [
              { "TransactionID": "45644090", "Perc": "4", "IsCS": "false" },
              { "TransactionID": "16674170", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "49994090", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "46564000", "Perc": "7", "IsCS": "false" },
              { "TransactionID": "46574000", "Perc": "3", "IsCS": "false" },
              { "TransactionID": "46604000", "Perc": "10", "IsCS": "false" },
              { "TransactionID": "46524000", "Perc": "14", "IsCS": "false" },
              { "TransactionID": "46504000", "Perc": "4", "IsCS": "false" },
              { "TransactionID": "50774150", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "52994000", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "43834170", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "15374090", "Perc": "2", "IsCS": "false" },
              { "TransactionID": "54284100", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "70710450", "Perc": "50", "IsCS": "false" }
            ]
          },
          "FutureElection": {
            "Security": [
              { "TransactionID": "45644090", "Perc": "4", "IsCS": "false" },
              { "TransactionID": "16674170", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "49994090", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "46564000", "Perc": "7", "IsCS": "false" },
              { "TransactionID": "46574000", "Perc": "3", "IsCS": "false" },
              { "TransactionID": "46604000", "Perc": "10", "IsCS": "false" },
              { "TransactionID": "46524000", "Perc": "14", "IsCS": "false" },
              { "TransactionID": "46504000", "Perc": "4", "IsCS": "false" },
              { "TransactionID": "50774150", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "52994000", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "43834170", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "15374090", "Perc": "2", "IsCS": "false" },
              { "TransactionID": "54284100", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "70710450", "Perc": "50", "IsCS": "false" }
            ]
          }
        },
        {
          "PlanID": "400014",
          "ServiceOption": "QualMRP",
          "Type": "403B",
          "Status": "Active",
          "TransactionRoutingID": "DAILY",
          "Reallocation": {
            "Security": [
              { "TransactionID": "16604085", "Perc": "3", "IsCS": "false" },
              { "TransactionID": "46164070", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "41024100", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "45334010", "Perc": "2", "IsCS": "false" },
              { "TransactionID": "51244250", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "15814140", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "51694020", "Perc": "14", "IsCS": "false" },
              { "TransactionID": "14784100", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "44264140", "Perc": "7", "IsCS": "false" },
              { "TransactionID": "41034070", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "56304360", "Perc": "24", "IsCS": "false" },
              { "TransactionID": "17164360", "Perc": "2", "IsCS": "false" },
              { "TransactionID": "16524360", "Perc": "5", "IsCS": "false" },
              { "TransactionID": "53684040", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "56314360", "Perc": "14", "IsCS": "false" },
              { "TransactionID": "55354250", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "59004070", "Perc": "21", "IsCS": "false" }
            ]
          },
          "FutureElection": {
            "Security": [
              { "TransactionID": "16604085", "Perc": "3", "IsCS": "false" },
              { "TransactionID": "46164070", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "41024100", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "45334010", "Perc": "2", "IsCS": "false" },
              { "TransactionID": "51244250", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "15814140", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "51694020", "Perc": "14", "IsCS": "false" },
              { "TransactionID": "14784100", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "44264140", "Perc": "7", "IsCS": "false" },
              { "TransactionID": "41034070", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "56304360", "Perc": "24", "IsCS": "false" },
              { "TransactionID": "17164360", "Perc": "2", "IsCS": "false" },
              { "TransactionID": "16524360", "Perc": "5", "IsCS": "false" },
              { "TransactionID": "53684040", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "56314360", "Perc": "14", "IsCS": "false" },
              { "TransactionID": "55354250", "Perc": "1", "IsCS": "false" },
              { "TransactionID": "59004070", "Perc": "21", "IsCS": "false" }
            ]
          }
        }
      ]
    }
  }
}


Request URL: Morningstar will send each transaction request to either the static URL shared with us during development phase, or to the ‘transurl’ attribute value provided during SSO to the Morningstar® Retirement ManagerSM web application. If we cannot determine the transaction URL by either of these means, we will throw an error. Dynamic querystring parameters are not supported in case of the static URL preconfigured on the Morningstar side. If client requires Morningstar to call a dynamic transaction URL for each session, that URL must be provided as part of each SSO request.

Transaction Response

Client must respond to Morningstar’s transaction request with an HTTP 200 OK response if transaction processing was successful. The response must also include a JSON object with three properties as detailed in the “TransactionExecutionResponse” object in the transaction schema file.

  1. Success – boolean property indicating the result of the transaction request
  2. ConfirmationIdentifier – string that uniquely identifies this response (Used for logging and debugging)
  3. ConfirmInformation – string that contains additional details about this transaction. This message will be displayed in our UI to the participant. This string can be HTML formatted.

An example of the transaction response is below:

{
"success":"true",
"confirmationIdentifier":"A1922BC0-EF57-4483-8E9E-CD15EDBA1D27",
"confirmInformation":"You have unenrolled successfully. Your confirmation number is <strong>1234</strong>"
}

In case of failure processing our transaction request due to unhandled exceptions, the appropriate HTTP error code should be sent. Details in the response body are not required in the error scenario. If failure is due to business exception, validation etc., client should send HTTP 200 OK response with the “success” property set to “false” in the response body.

Security and Authentication

The following security mechanisms are supported when sending a transaction request:

  1. apiKey request header – Each transaction request will include an HTTP Header named “apiKey” which will have a value provided by the client during initial setup.
  2. Basic Authentication: Basic Authentication header is supported. Username and password will be provided by client during setup.
  3. OAuth 2.0: Only Client credentials Grant Type is supported. Scope is presently not supported
  4. A combination of apiKey and Basic Authentication is also supported
  5. Mutual TLS: Presently not supported

Transaction FAQ

Q: Is there an OpenAPI schema for the transaction request and response?

A: The OpenAPI v3 schema specification for transaction request and response is included in the transaction schema included in this document.

Q: Is the API contract backwards compatible?

A: We will ensure that future changes to our transaction payloads are backwards compatible. We will inform clients well in advance when any significant or breaking changes are planned.

Q: What is the Content Type of the transaction payload?

A: The transaction payload is sent with the Content-Type header value of “application/json”.

Q: Is the transaction request asynchronous?

A: No. We will send transaction payloads via an HTTP POST request to an endpoint that the client will host. We expect a synchronous response to our calls within 60 seconds. If we do not receive a response in 60 seconds, we show an error in our application.

Q: How does the client provide the OAuth credentials to Morningstar?

A: Please provide the credentials via email during the initial setup phase.

Q: What should be the Content-Type of the response?

A: The response should be sent as a JSON object of the type ‘TransactionExecutionResponse’ defined in our OpenAPI schema specification file.

Q: Do you support passing custom HTTP headers as part of the transaction request?

A: We presently do not support adding custom headers to our transaction HTTP request.

Q: What is the expected volume of requests that will be sent by Morningstar?

A: The volume of transaction requests depends on the number of people who are coming into Morningstar® Retirement ManagerSM from the client website and are signing up for our service.

Q: Does Morningstar have a default configured HTTP timeout for each transaction request?

A: We expect a response with 60 seconds.

Q: What HTTP response codes are expected as part of the response?

A: For errors that can be captured (business errors, some validation errors) before the response is sent back, please send an HTTP 200 with success=false in the response and a description of the issue in the confirmInformation property. We will display that information to the participant in our UI.

The following is an example of an HTTP 200:

{
"success": "false",
"confirmationIdentifier": "A1922BC0-EF57-4483-8E9E-CD15EDBA1D27",
"confirmInformation": "You enrollment cannot be processed because another enrollment is already pending."
}

For any unhandled exceptions that result in an HTTP response code other than HTTP 200, our application will throw an exception and the UI would show a generic error popup message to the participant. ConfirmInformation property is of type string (It can be valid html string) and in case of success, its value is displayed to the participant within Morningstar® Retirement ManagerSM UI.

Q: Is Morningstar using the latest version of OAuth?

A: We support OAuth 2.0 with Grant Type of Client Credentials only. We can make a call to fetch a token first from the client’s token endpoint, and then include that Bearer token in the Authorization header while posting the transaction to the client’s transaction endpoint. We do not support setting of “Scope” for a token request.

IP Ranges

Our transaction requests in UAT and Production environments will originate from the following IP addresses. If required, clients should add these IP addresses to the allow list in their Firewalls.

Amazon US-East (Primary Data Center)Amazon US-West (Backup Data Center)
107.22.234.12344.238.193.3
3.228.196.11135.82.125.46
34.193.75.8954.188.19.121
34.196.130.7354.69.183.6
34.238.71.25