Brazil Dividend Disclosures API: Track JCP and Payout Notices from CVM Filings

The problem

Dividend research on B3 issuers breaks into two stacks that SERPs often mix:

1. Quotes and market data — OHLCV, dividend yield, sometimes a cash dividend history. Good for charts, not for the filing text your compliance or NLP pipeline must cite.
2. Regulatory disclosures — avisos aos acionistas and material facts that announce or amend payouts. These live in CVM's IPE layer, not in a stock quote JSON field.

Scraping the CVM portal works for one ticker and fails on a watchlist. Bulk open-data ZIPs are dataset-oriented, not ticker-first. You want GET /v1/documents with stable document.id, then GET /v1/documents/:id/file for the original PDF — the same pattern as Brazil IPE disclosures, scoped to payout events.

For the quotes vs filings split, see Quotes API vs CVM filings API and Brazil financial data API.

Which filing type carries the payout?

Brazilian issuers do not use a single SEC-style "dividend form." Payout-related information typically appears under two apicvm type values:

Practical rule: start with AVISO_AOS_ACIONISTAS for structured payout notices; add FATO_RELEVANTE when you monitor earnings-season clusters or want the same loop as material facts monitoring. Filter downloaded PDFs by keywords (dividendo, JCP, juros sobre capital) if you poll both types.

On VALE3 for calendar year 2026, the demo corpus held 1 AVISO_AOS_ACIONISTAS row (demo API, queried 2026-09-10). Active issuers file more notices in payout-heavy years; zero rows does not prove no dividend occurred — see limitations below.

Step-by-step list queries for avisos: List Brazil shareholder notices via API.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List payout-related filings — GET /v1/documents with type=AVISO_AOS_ACIONISTAS or types=AVISO_AOS_ACIONISTAS,FATO_RELEVANTE
3. Scope with year and optional dateRef
4. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
5. Optional (Pro): page-level markdown — POST /v1/document-text-extractions with async callback

Auth: Authorization: Bearer or X-API-Key. Try VALE3 without a key via the demo API.

Setup

export APICVM_KEY='apicvm_...'
export APICVM_URL='https://apicvm.dev'

Step 1: List shareholder notices for one ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=AVISO_AOS_ACIONISTAS&year=2026&perPage=50"

Response rows include stable id, dateRef, name, and nested company metadata. Use id as your cache key — not name, which can be long and encoding-sensitive.

Paginate with page= when meta.lastPage > 1. perPage maxes at 50.

Step 2: Combine payout-related types in one call

During earnings season, issuers may file a material fact and an aviso in the same window:

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&types=AVISO_AOS_ACIONISTAS,FATO_RELEVANTE&year=2026&perPage=50&field=dateRef&order=desc"

See Track Brazil earnings season for the broader ITR + presentation + material fact bundle.

Step 3: Download a payout notice PDF

curl -H "Authorization: Bearer $APICVM_KEY" \
  -o payout-notice.pdf \
  "$APICVM_URL/v1/documents/<document-id>/file"

Download does not consume extraction credits.

Example: Python watchlist for payout filings

Poll avisos (and optionally material facts) across a dividend-focused watchlist. Persist seen in your database in production.

import os, time, requests
from datetime import datetime

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}
WATCH = ["VALE3", "PETR4", "ITUB4", "BBDC4", "ABEV3"]
YEAR = datetime.utcnow().year
PAYOUT_TYPES = "AVISO_AOS_ACIONISTAS,FATO_RELEVANTE"
seen = set()  # load from your store on startup

def list_payout_docs(ticker):
    r = requests.get(
        f"{BASE}/v1/documents",
        headers=H,
        params={
            "ticker": ticker,
            "types": PAYOUT_TYPES,
            "year": YEAR,
            "perPage": 50,
            "field": "dateRef",
            "order": "desc",
        },
    )
    if r.status_code == 429:
        time.sleep(5)
        return list_payout_docs(ticker)
    r.raise_for_status()
    return r.json()["data"]

for ticker in WATCH:
    for doc in list_payout_docs(ticker):
        if doc["id"] in seen:
            continue
        seen.add(doc["id"])
        if doc["type"] == "AVISO_AOS_ACIONISTAS":
            print(f"AVISO {ticker} {doc['dateRef']} {doc['name'][:70]}")
        # Optionally filter FATO_RELEVANTE by filename keywords before alerting

Wire this into GitHub Actions or extend the diff pattern from Brazil material facts monitoring API.

Where dividend disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. Brazil financial statements API covers DFP/ITR for the periodic side.

Current limitations

• Documents, not dividend yield series — apicvm does not replace a quotes API for historical yield or payment calendars derived from market data.
• Polling, not push — no webhook when CVM publishes a new aviso. Schedule polls and diff document.id.
• Ingestion lag — sync is not real-time. A notice may appear on the portal before it is in the corpus.
• Corpus coverage — not every issuer or period is present. Validate against the portal for production compliance use cases.
• Demo scope — /v1/demo/* is limited to VALE3. Other tickers need a production key.

Next steps

• Read the API docs
• Get an API key
• List Brazil shareholder notices — focused AVISO_AOS_ACIONISTAS reference

Related guides

• Brazil IPE disclosures API — all five IPE types
• Extract text from CVM PDFs for AI agents — async markdown extraction
• Build a multi-ticker CVM filings watchlist