openapi: 3.0.1
info:
version: 1.0.0
title: Authorization Tokens Accounts Corporate Actions 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: Corporate Actions
paths:
/direct-web-services/time-series/v1/corporate-actions/dividend-amount-history/{ids}:
get:
tags:
- Corporate Actions
summary: Get Dividend Amount History time series.
description: Historical Dividends, Capital Gains and Split Factor.
parameters:
- name: ids
in: path
description: "\nComma-separated list of up to 25 investment identifiers to query.\n\nAccepts:\n\n- Morningstar Performance ID (default)\n- Morningstar Security ID\n- Morningstar IDs (MSID)\n- ISIN\n- CUSIP\n- Trading symbol\n- Category ID \n Important: When a category ID is passed, the corresponding `identifierType` can be `performanceId` or `securityId`. The value must be URL-encoded. For example, if the category ID is `LC00002226;CA]FO`, the URL-encoded value is `LC00002226;CA%5DFO`."
required: true
schema:
type: string
example: 0P00000016,0P00002Y8D,DODGX,0P000000ppY
- name: idTypes
in: query
description: '
Comma-separated list specifying the type of each value passed in the `ids` parameter.<br>
Rules:
* Values must align with the order of values in `ids`
* Use empty entries to skip
* Omit trailing commas after the last non-empty value
* Empty values default to `performanceId`
Example:
* `ids=id1,id2,id3`
* `id1` and `id3` are performance IDs
* `id2` is a security ID
* `idTypes=,securityId`
Accepted values:
* `performanceId` (default)
* `isin`
* `securityId`
* `cusip`
* `tradingSymbol`
* `msid`'
schema:
type: string
example: ',securityId'
- name: baseCurrency
in: query
description: '
Comma-separated list of 3-character ISO 4217 currency codes (for example, `CAD`, `EUR`, `JPY`).<br>
* Filters results based on currency
* Values must align with the order of values in `ids`
* Use empty entries to skip
* Omit trailing commas after the last non-empty value
Example:
* `ids=id1,id2,id3,id4,id5`
* Base currency passed for `id2` and `id4`
* `baseCurrency=,USD,,USD`'
schema:
type: string
example: ',USD,,USD'
- name: domicile
in: query
description: "\nComma-separated list of 3-character ISO 3166‑1 country codes (for example, `CAN`, `IRL`, `IND`). \nRules:\n\n* Filters results based on domicile\n* Values must align with the order of values in `ids`\n* Use empty entries to skip\n* Omit trailing commas after the last non-empty value\n\nExample:\n\n* `ids=id1,id2,id3,id4,id5`\n* Domicile passed for `id2` and `id4`\n* `domicile=,USA,,USA`"
schema:
type: string
example: ',USD,,USD'
- name: exchangeCountry
in: query
description: '
Comma-separated list of 3-character ISO 3166‑1 country codes (for example, `CAN`, `IRL`, `IND`).
* Filters results based on domicile
* Values must align with the order of values in `ids`
* Use empty entries to skip
* Omit trailing commas after the last non-empty value
Example:
* `ids=id1,id2,id3,id4,id5`
* Exchange country passed for `id2` and `id4`
* `exchangeCountry=,USA,,USA`'
schema:
type: string
example: ',CAN,CAN'
- name: exchangeId
description: '
Comma-separated list of exchange IDs (for example, `EX$$$$XMEX`, `EX$$$$XNAS`).
* Filters results based on exchange ID
* Values must align with the order of values in `ids`
* Use empty entries to skip
* Omit trailing commas after the last non-empty value
Example:
* `ids=id1,id2,id3,id4,id5`
* Exchange ID passed for `id2` and `id4`
* `exchangeId=,EX$$$$XMEX,,EX$$$$XNAS`'
in: query
required: false
schema:
type: string
example: EX$$$$XMEX
- name: frequency
in: query
description: Specifies the time interval between data points.
schema:
enum:
- daily
type: string
default: daily
- name: startDate
in: query
description: 'Specifies the start date for the time series. Accepted format is `yyyy-MM-dd`.
'
schema:
type: string
example: '2020-01-12'
format: date
- name: endDate
in: query
description: 'Specifies the end date for the time series. Accepted format is `yyyy-MM-dd`.
'
schema:
type: string
example: '2024-01-12'
format: date
- name: timePeriod
in: query
description: "Specifies the size of the time window for the data range. \n\n- Used in combination with `timePeriodUnit` to specify relative time ranges. \n\n- When `startDate`, `endDate`, `timePeriod` and `timePeriodUnit` are provided, `timePeriod` and `timePeriodUnit` take precedence."
schema:
type: number
example: '12'
- name: timePeriodUnit
in: query
description: "\nSpecifies the time period unit. \n\n- Used in combination with `timePeriod` to specify relative time ranges. \n\n- When `startDate`, `endDate`, `timePeriod` and `timePeriodUnit` are provided, `timePeriod` and `timePeriodUnit` take precedence."
schema:
type: string
enum:
- months
- days
- years
- name: applyEarliestCommonDate
in: query
description: "\nSpecifies whether to apply the earliest common start date across all investments.\n\n When set to `true`, the start date of the time series is adjusted to match the latest inception date among the investments, ensuring all data points are aligned."
schema:
type: boolean
default: false
- name: applyTrackRecordExtension
in: query
description: '
Specifies whether to apply the Track Record Extension logic in order to extend the performance of an investment by copying the historical performance of another qualified older investment.'
schema:
type: boolean
default: false
- name: applyRestructureDate
in: query
description: '
Specifies whether to consider the Morningstar or Custom restructure date when determining the start of the performance period.
This option is applicable only when `applyEarliestCommonDate` is set to true.'
schema:
type: boolean
default: false
- name: sinceInception
in: query
description: "\nSets the time range from inception (or the maximum supported lookback) to the end date. \n\nTakes precendence over any `timePeriod` / `timePeriodUnit` and `startDate` / `endDate` settings."
required: false
schema:
type: boolean
default: false
- name: currencyId
in: query
description: Specifies the currency in which to return data.
schema:
type: string
enum:
- BASE
- AUD
- BND
- BRL
- CAD
- CHF
- CLP
- CNH
- CNY
- CZK
- DKK
- EUR
- GBP
- HKD
- HUF
- IDR
- ILS
- INR
- JPY
- KRW
- MOP
- MXN
- MYR
- NOK
- NZD
- PLN
- RMB
- RUB
- SEK
- SGD
- THB
- TWD
- USD
- ZAR
default: BASE
responses:
'200':
$ref: '#/components/responses/ResponseTimeSeriesSingleObservation'
'400':
$ref: '#/components/responses/ResponseStatus400'
'500':
$ref: '#/components/responses/ResponseStatus500'
operationId: getCorporateActionsDividendAmountHistory
components:
schemas:
OutputMetadataMessages:
description: Provides information about identifiers for which no results were returned.
title: OutputMetadataMessages
type: object
additionalProperties: false
properties:
investments:
description: Indicates identifiers for which no results were returned.
type: array
items:
$ref: '#/components/schemas/OutputMetadataMessageInvestment'
type:
type: string
description: Indicates the message type.
example: Warning
readOnly: true
const: Warning
message:
type: string
description: Description of the issue encountered.
example: 'Lookup : Invalid investments.'
readOnly: true
code:
type: string
description: Code associated with the message.
example: 404.common.125
readOnly: true
ResponseTimeSeriesSingleObservation:
title: ResponseTimeSeriesSingleObservation
readOnly: true
description: List of investments for which time series data was returned.
type: object
additionalProperties: false
properties:
investments:
type: array
minItems: 1
items:
$ref: '#/components/schemas/OutputInvestmentSingleObservation'
metadata:
$ref: '#/components/schemas/OutputMetadata'
OutputTimeSeriesSingleObservation:
title: OutputTimeSeriesSingleObservation
type: object
description: A named time series with dated data points.
additionalProperties: false
properties:
categories:
type: array
description: Semantic tags/labels for this series.
items:
$ref: '#/components/schemas/OutputCategory'
dataPoint:
description: Data point time series relates to.
type: string
example: daily-price
enum:
- 12-mo-yield
- 7-day-gross-yield
- 7-day-unsubsidized-yield
- 7-day-yield
- absolute-carbon-emissions-scope-1-and-2-tonnes
- absolute-carbon-emissions-scope-1-and-2-tonnes-category-average
- absolute-carbon-intensity-scope-1-and-2-tonnes-per-usd-millions
- absolute-carbon-intensity-scope-1-and-2-tonnes-per-usd-millions-category-average
- accounting-fee
- administrator-fee
- advisor-fee
- aggregated-12-month-yield
- aggregated-sec-yield
- annual-ongoing-charge-excluding-performance-fee
- annual-ongoing-charge-including-performance-fee
- annual-report-adjusted-expense-ratio
- annual-report-management-expense-ratio-mer
- annual-report-ongoing-charge
- borrowing-costs-actual
- borrowing-costs-estimated
- carbon-footprint-scope-1-and-2-and-3-tonnes-per-usd-millions
- carbon-footprint-scope-1-and-2-and-3-tonnes-per-usd-millions-category-average
- carbon-footprint-scope-1-and-2-eligible-holding-type
- carbon-footprint-scope-1-and-2-number-of-holdings-covered
- carbon-footprint-scope-1-and-2-percentage-of-eligible-portfolio-covered
- carbon-footprint-scope-1-and-2-percentage-of-eligible-portfolio-not-covered
- carbon-footprint-scope-1-and-2-percentage-of-portfolio-covered
- carbon-footprint-scope-1-and-2-percentage-of-portfolio-eligible
- carbon-footprint-scope-1-and-2-percentage-of-portfolio-eligible-not-covered
- carbon-footprint-scope-1-and-2-percentage-of-portfolio-not-covered
- carbon-footprint-scope-1-and-2-percentage-of-portfolio-not-eligible
- carbon-footprint-scope-1-and-2-tonnes-per-aud-million-category-average
- carbon-footprint-scope-1-and-2-tonnes-per-aud-millions
- carbon-footprint-scope-1-and-2-tonnes-per-chf-million-category-average
- carbon-footprint-scope-1-and-2-tonnes-per-chf-millions
- carbon-footprint-scope-1-and-2-tonnes-per-eur-million-category-average
- carbon-footprint-scope-1-and-2-tonnes-per-eur-millions
- carbon-footprint-scope-1-and-2-tonnes-per-gbp-million-category-average
- carbon-footprint-scope-1-and-2-tonnes-per-gbp-millions
- carbon-footprint-scope-1-and-2-tonnes-per-hkd-million-category-average
- carbon-footprint-scope-1-and-2-tonnes-per-hkd-millions
- carbon-footprint-scope-1-and-2-tonnes-per-sgd-million-category-average
- carbon-footprint-scope-1-and-2-tonnes-per-sgd-millions
- carbon-footprint-scope-1-and-2-tonnes-per-usd-millions
- carbon-footprint-scope-1-and-2-tonnes-per-usd-millions-category-average
- carbon-risk-level-classification
- carbon-risk-score-category-average
- carbon-risk-score-percent-rank-in-category
- cum-fair-nav-unweighted-dri
- cum-fair-nav-weighted-dri
- current-yield
- cumulative-return
- daily-closing-price
- daily-estimated-holding-cost
- daily-gross-return-index
- daily-high-price
- daily-load-adj-return-index-restated
- daily-low-price
- daily-market-impact-cost
- daily-market-return-index
- daily-net-return-index
- daily-portfolio-concentration
- daily-price
- daily-return-index
- daily-return-index-cum-fair
- daily-tracking-volatility
- daily-volume
- daily-yield
- distribution-fee-percentage-of-nav-actual
- distribution-fee-percentage-of-nav-estimated
- dividend-amount-history
- dividend-yield-12-month
- dividend-yield-long
- dividend-yield-short
- entry-cost-acquired-actual
- equity-mkt-cap-rescaling-factor-long
- estimated-quarterly-return
- estimated-share-class-net-flow-daily
- estimated-share-class-net-flow-monthly
- ex-par-nav-unweighted-dri
- ex-par-nav-weighted-dri
- growth
- five-year-five-star-rating-percent
- five-year-four-star-rating-percent
- five-year-not-star-rated-percent
- five-year-not-star-rating-eligible-percent
- five-year-one-star-rating-percent
- five-year-three-star-rating-percent
- five-year-two-star-rating-percent
- historical-carbon-risk-score
- historical-corporate-esg-risk-score
- historical-sovereign-esg-risk-score
- income-only-yield-nav-uk
- income-only-yield-nav-us
- income-only-yield-price-us
- indirect-costs-closed-ended-actual-uk
- indirect-costs-closed-ended-estimated-uk
- indirect-costs-open-ended-actual-uk
- indirect-costs-open-ended-estimated-uk
- management-fee-ex-distribution-fees-actual
- management-fee-ex-distribution-fees-estimated
- market-cap-giant-percentage-long-rescaled
- market-cap-large-percentage-long-rescaled
- market-cap-micro-percentage-long-rescaled
- market-cap-mid-percentage-long-rescaled
- market-cap-small-percentage-long-rescaled
- maximum-entry-cost-acquired
- maximum-entry-cost-base-currency
- maximum-entry-cost-percentage
- maximum-exit-cost-acquired
- maximum-exit-fee-base-currency
- maximum-exit-fee-percentage
- model-representative-cost
- monthly-downside-tracking-error
- monthly-gross-return
- monthly-inflation-adjusted-return
- monthly-load-adj-return-restated
- monthly-market-return
- monthly-net-return
- monthly-return
- monthly-return-unweighted-nav
- monthly-return-unweighted-price
- monthly-return-weighted-nav
- monthly-return-weighted-price
- monthly-tracking-error
- monthly-yield
- morningstar-esg-risk-rating-for-funds
- morningstar-medalist-rating
- morningstar-medalist-rating-parent-pillar
- morningstar-medalist-rating-parent-pillar-type
- morningstar-medalist-rating-people-pillar
- morningstar-medalist-rating-people-pillar-type
- morningstar-medalist-rating-performance-pillar
- morningstar-medalist-rating-performance-pillar-type
- morningstar-medalist-rating-price-pillar
- morningstar-medalist-rating-price-pillar-type
- morningstar-medalist-rating-process-pillar
- morningstar-medalist-rating-process-pillar-type
- morningstar-medalist-rating-type
- morningstar-rating-overall
- nav-unweighted-daily-income-and-capital-gain-yield
- nav-unweighted-daily-income-only-yield
- nav-unweighted-daily-total-distribution-yield
- nav-unweighted-dri
- nav-weighted-daily-income-and-capital-gain-yield
- nav-weighted-daily-income-only-yield
- nav-weighted-daily-total-distribution-yield
- nav-weighted-dri
- ongoing-charge-ex-perf-fee
- ongoing-charge-inc-perf-fee
- ongoing-cost-actual
- ongoing-cost-estimated
- other-fee
- other-fee-amount-cn
- overall-five-star-rating-percent
- overall-four-star-rating-percent
- overall-not-star-rated-percent
- overall-not-star-rating-eligible-percent
- overall-one-star-rating-percent
- overall-three-star-rating-percent
- overall-two-star-rating-percent
- performance-fee-actual
- performance-fee-estimated
- portfolio-carbon-risk-score
- portfolio-corporate-esg-risk-rating
- portfolio-corporate-esg-risk-score
- portfolio-environmental-risk-score
- portfolio-governance-risk-score
- portfolio-social-risk-score
- portfolio-sovereign-esg-risk-rating
- portfolio-sovereign-esg-risk-score
- portfolio-unallocated-risk-score
- price
- price-unweighted-daily-income-and-capital-gain-yield
- price-unweighted-daily-income-only-yield
- price-unweighted-daily-total-distribution-yield
- price-unweighted-dri
- price-weighted-daily-income-and-capital-gain-yield
- price-weighted-daily-income-only-yield
- price-weighted-daily-total-distribution-yield
- price-weighted-dri
- prospective-acquired-fund-expense
- prospectus-adjusted-expense-ratio
- quarterly-downside-tracking-error
- quarterly-gross-return
- quarterly-inflation-adjusted-return
- quarterly-load-adj-return-restated
- quarterly-market-return
- quarterly-net-return
- quarterly-return
- quarterly-tracking-error
- quoted-yield-daily
- rating-10-yr
- rating-3-yr
- rating-5-yr
- raw-return-cum-fair
- raw-return-market-price
- raw-return-nav
- real-assets-costs-actual-uk
- real-assets-costs-estimated-uk
- return
- rolling-return
- sec-yield
- sec-yield-rescaling-factor
- sitca-yield
- sri-value
- ten-year-five-star-rating-percent
- ten-year-four-star-rating-percent
- ten-year-not-star-rated-percent
- ten-year-not-star-rating-eligible-percent
- ten-year-one-star-rating-percent
- ten-year-three-star-rating-percent
- ten-year-two-star-rating-percent
- three-year-five-star-rating-percent
- three-year-four-star-rating-percent
- three-year-not-star-rated-percent
- three-year-not-star-rating-eligible-percent
- three-year-one-star-rating-percent
- three-year-three-star-rating-percent
- three-year-two-star-rating-percent
- total-expense-survey
- trading-expense
- transaction-costs-actual-uk
- transaction-costs-estimated-uk
- transaction-fee-actual
- transaction-fee-estimated
- turnover-ratio-percentage
- typical-exit-cost
- unannualized
- weekly-return
- yearly-capital-return
- yearly-gross-return
- yearly-income-return
- yearly-inflation-adjusted-return
- yearly-interest-income
- yearly-investor-return
- yearly-load-adj-return-restated
- yearly-market-return
- yearly-net-return
- yearly-return
performanceType:
type: string
description: Indicates the performance type used for the time series.
enum:
- total
- market
- gross
data:
type: array
items:
$ref: '#/components/schemas/DataModelSingleObservation'
ErrorResponse:
title: ErrorResponse
description: Defines the structure of an error response returned when a bad or invalid request is submitted. Includes the HTTP status code, descriptive message, and request identifier for traceability.
type: object
properties:
statusCode:
description: Numeric HTTP status code associated with the error.
type: integer
format: int32
example: 400
readOnly: true
errorCode:
description: Identifier for a specific type of error.
type: string
example: 400.timeSeries.009
readOnly: true
message:
type: string
description: Descriptive message providing details about the error or validation failure.
example: Invalid frequency 'm' for datapoint 'daily-closing-price'.
readOnly: true
requestId:
description: Indicates unique request identifier.
example: c63e7f6c-b52d-42c3-9d1b-4a4b4ac05f3c
readOnly: true
type: string
additionalProperties: false
OutputInvestmentSingleObservation:
title: OutputInvestmentSingleObservation
type: object
additionalProperties: false
properties:
identifiers:
$ref: '#/components/schemas/OutputIdentifiers'
timeSeries:
$ref: '#/components/schemas/OutputTimeSeriesSingleObservation'
metadata:
$ref: '#/components/schemas/OutputInvestmentsMetadata'
OutputCategory:
title: OutputCategory
type: string
description: Identifies the thematic category or functional area a data point belongs to within the Time Series API.
enum:
- fees-expenses
- corporate-actions
- fund-sustainability
- fund-research
- performance
- portfolio-analytics
- portfolio-holdings
- reference
OutputIdentifiers:
title: OutputIdentifiers
description: Specifies the identifier type used to specify the target investment in the request.
additionalProperties: false
properties:
performanceId:
type: string
example: 0P00002CI5
isin:
type: string
example: US2562191062
securityId:
type: string
example: FCUSA0000P
cusip:
type: string
example: 459200101
sedol:
type: string
example: B4TT7L5
tradingSymbol:
type: string
example: MDLOX
OutputMetadataMessageInvestment:
title: OutputMetadataMessageInvestment
type: object
additionalProperties: false
properties:
id:
type: string
description: Indicates identifier value passed in request.
example: 0P000PPP6Q
readOnly: true
idType:
type: string
description: Indicates the identifier type passed in request.
example: performanceId
readOnly: true
OutputMetadata:
description: Metadata returned in response. Includes information about identifiers for which no results were found.
title: OutputMetadata
type: object
properties:
messages:
$ref: '#/components/schemas/OutputMetadataMessages'
requestId:
description: Indicates the request identifier.
example: c63e7f6c-b52d-42c3-9d1b-4a4b4ac05f3c
type: string
readOnly: true
time:
description: Indicates time response was returned.
example: '2025-10-02T10:54:36.9161062Z'
type: string
format: date-time
readOnly: true
additionalProperties: false
OutputInvestmentsMetadata:
title: OutputInvestmentsMetadata
description: Provides the identifier look up details passed in request.
type: object
additionalProperties: false
properties:
exchangeCountry:
type: string
example: GBR
default: USA
description: Indicates exchange country used to look up investment. Represented by 3-character ISO 3166-1 country codes.
minLength: 3
maxLength: 3
domicile:
type: string
example: GBR
default: USA
description: Indicates domicile used to look up investment. Represented by 3-character ISO 3166-1 country codes.
minLength: 3
maxLength: 3
baseCurrency:
type: string
example: GBP
default: USD
description: Indicates base currency used to look up investment. Represented by 3-character ISO 4217 currency codes.
minLength: 3
maxLength: 3
DataModelSingleObservation:
title: DataModelSingleObservation
description: Represents a time series of single observations, where each entry contains a date and its corresponding value.
type: object
properties:
date:
type: string
format: date
example: '2025-09-06'
value:
type: number
example: 1.108
examples:
ResponseStatus400Example1:
summary: 400 - Bad Request
value:
statusCode: 400
errorCode: 400.investmentDetails.002
message: Invalid date format. Expected format is yyyy-MM-d
requestId: 539d62a5-3586-4070-965e-0f7f64712d79
ResponseStatus500Example1:
summary: 500 - Internal Server Error
value:
statusCode: 500
errorCode: 500.investmentDetails.003
message: Error calling Investment API.
requestId: 539d62a5-3586-4070-965e-0f7f64712d79
responses:
ResponseStatus500:
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ResponseStatus500Example1:
$ref: '#/components/examples/ResponseStatus500Example1'
ResponseTimeSeriesSingleObservation:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseTimeSeriesSingleObservation'
ResponseStatus400:
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ResponseStatus400Example1:
$ref: '#/components/examples/ResponseStatus400Example1'
securitySchemes:
BasicAuth:
type: http
scheme: basic