API Reference: Splits and Dividends
Details
Docs navigation
- Getting started: Quickstart, Authentication, Rate limits, Errors and retries
- Guides: Symbol formats, Timestamps and time zones, Pagination, Split and dividend adjustments, WebSocket streaming, Dataset downloads, Excel and Google Sheets, Changelog
- API reference: Stock bars, Stock trades and quotes, Snapshots and movers, Tickers, exchanges, calendar, Splits and dividends (you are here), Fundamentals and SEC filings, Options chain and Greeks, Options EOD, bars, OI, Forex, Crypto, Crypto derivatives, Futures bars and continuous, Settlements and COT, Indices, Economic data, Technical indicators
- SDKs: Python, JavaScript
One endpoint returns every event that changes a stock's price history or identity: cash and stock dividends, splits and reverse splits, ticker changes, mergers, spinoffs and delistings. This reference covers the dividends API endpoint and its filters, every field it returns, and how to use adjustment_factor to adjust prices yourself. Dividend traders, anyone adjusting raw prices and anyone tracking ticker changes will need it.
Early access. Planned v1 endpoint, not live yet. Free gets 2 years of dividends and splits. Starter ($29/mo) gets full history plus symbol changes, mergers and adjustment factors. Business ($249/mo) for commercial use.
Details
List corporate actions
GET https://api.marketdata.co/v1/stocks/corporate-actions
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
symbol |
string | no | all | Ticker. Omit to get every company's events in the date range |
action_type |
string | no | all | Comma-separated: cash_dividend, stock_dividend, split, reverse_split, symbol_change, merger, spinoff, delisting |
start |
string | no | 2 years ago | Earliest ex_date, inclusive |
end |
string | no | 1 year ahead | Latest ex_date, exclusive. Future dates return announced events |
date_field |
string | no | ex_date |
Filter on ex_date, declaration_date, record_date or pay_date |
updated_since |
string | no | Only events created or changed after this UTC time | |
limit |
integer | no | 1,000 | Max 10,000 |
cursor, format |
string | no | Paging, json or csv |
Response fields
| Field | Type | Description |
|---|---|---|
symbol |
string | Ticker at the time of the event |
event_id |
string | Our stable ID for the event |
action_type |
string | See values above |
ex_date |
string | Ex-date, or effective date for splits and changes |
declaration_date |
string | Announcement date (optional) |
record_date |
string | Record date (optional) |
pay_date |
string | Payment date (optional) |
cash_amount |
number | Dividend per share (optional) |
currency |
string | Dividend currency (optional) |
frequency |
number | Payments per year, 0 for one-off (optional) |
dividend_type |
string | regular, special, return_of_capital (optional) |
split_from, split_to |
number | 1 and 4 in a 4-for-1 split (optional) |
old_symbol, new_symbol |
string | For symbol changes (optional) |
adjustment_factor |
number | Multiplier for prices before ex_date (optional) |
isin, figi |
string | Identifiers (optional) |
updated_at |
string | Last change to this record, UTC |
Example request
Example (curl), Coca-Cola cash dividends:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.marketdata.co/v1/stocks/corporate-actions?symbol=KO&action_type=cash_dividend&start=2020-01-01"
Example (Python), every split in the market next month:
import os
import requests
import pandas as pd
r = requests.get(
"https://api.marketdata.co/v1/stocks/corporate-actions",
headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
params={"action_type": "split,reverse_split", "start": "2026-12-01", "end": "2027-01-01"},
)
splits = pd.DataFrame(r.json()["results"])
print(splits[["symbol", "ex_date", "split_from", "split_to"]])
Example response
{
"status": "ok",
"count": 1,
"next_cursor": null,
"results": [
{
"symbol": "KO",
"event_id": "ca_20261128_KO_div",
"action_type": "cash_dividend",
"ex_date": "2026-11-28",
"declaration_date": "2026-10-16",
"record_date": "2026-11-28",
"pay_date": "2026-12-15",
"cash_amount": 0.51,
"currency": "USD",
"frequency": 4,
"dividend_type": "regular",
"adjustment_factor": 0.99282,
"isin": "US1912161007",
"figi": "BBG000BMX289",
"updated_at": "2026-10-16T20:41:12Z"
}
]
}
Amounts and dates are an example from our schema, not a confirmed announcement.
Details
Using adjustment_factor
To adjust raw history yourself, multiply every price dated before ex_date by adjustment_factor. With several events, multiply the factors of every later event together. For splits the factor is split_from / split_to; for cash dividends it is 1 - cash_amount / previous_close. The adjustments guide has the full method and code.
API
Errors for this endpoint
| HTTP | error.code |
When |
|---|---|---|
| 400 | invalid_parameter |
Unknown action_type or date_field |
| 400 | range_too_large |
No symbol and a range over 1 year; narrow it or page through |
| 403 | plan_required |
History beyond 2 years, or symbol changes and mergers, on Free |
| 404 | symbol_not_found |
Unknown ticker |
Watch out
Notes and gotchas
symbolis the ticker at the time of the event. After a ticker change, older events keep the old symbol; followsymbol_changerecords to link them.- Since the US moved to T+1 settlement in May 2024, the ex-date and record date for most regular dividends fall on the same day. Older records show the ex-date one business day before the record date.
- Announced but future events can still change. Poll with
updated_sinceto pick up revisions. frequencyis our reading of the payment pattern. A company that skips a quarter can show a changed value later.- Special dividends are marked
dividend_type: "special". Exclude them when you compute a regular yield. - Reverse splits have
split_fromgreater thansplit_to, so the factor is above 1.
Keep reading
Next steps
Details
Was this page useful?
[Yes] [No]
Found a missing or wrong event? Report it on the custom data form.