Early access is open. Free sample datasets are live now. Download a sample

API Reference: Splits and Dividends

Details

Docs navigation

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

  • symbol is the ticker at the time of the event. After a ticker change, older events keep the old symbol; follow symbol_change records 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_since to pick up revisions.
  • frequency is 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_from greater than split_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.