List Brazil Shareholder Notices (Avisos aos Acionistas) via API

The problem

Payout workflows are event-driven, and the event is a document:

• A dividend or JCP announcement with per-share amounts, record date, and payment date
• A capital increase with subscription rights and a subscription window
• A stock split or reverse split that changes every position and price series you store

Market data providers hand you a cleaned dividend series. That series is downstream of these filings, and it usually arrives after the fact, without the terms and conditions written by the issuer. Going to the primary source means the CVM portal, where notices sit next to material facts and generic communications with no stable typed filter and no per-document identifier you can persist.

What "shareholder notice" means here

In the apicvm contract, IPE-style disclosures are split into distinct types so you can subscribe to one event class at a time:

A single corporate action often produces more than one of these. A dividend approved at a shareholders' meeting can show up as an ata documenting the vote and an aviso setting the payment terms. Filter by the type that matches the fact you need, not by the event you have in mind.

CVM is Brazil's securities regulator, so if you work with SEC EDGAR the workflow will feel familiar — but the taxonomy is Brazilian and there is no one-to-one mapping to a US form.

IPE filings are single PDFs. Section prefixes (GET /v1/document-prefixes) still apply only to DFP, ITR, and FRE.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List notices — GET /v1/documents?type=AVISO_AOS_ACIONISTAS
3. Download the PDF — GET /v1/documents/:id/file
4. Optional (Pro): enqueue page-level markdown — POST /v1/document-text-extractions

Auth: Authorization: Bearer or X-API-Key.

Setup

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

The public demo API is scoped to VALE3 FRE risk factors, so it will not serve shareholder notices. Use a real key for this flow.

Step 1: Resolve the company

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/companies/resolve?query=PETR4&by=ticker"

Confirm cnpj and tickers[] before you store anything. A name query that matches more than one issuer returns 409 AMBIGUOUS_RESULT with candidates — tighten it with by=ticker or by=cnpj. Holding companies with several share classes are the usual source of ambiguity, and payout notices are exactly where class matters.

Step 2: List avisos aos acionistas

Filter by ticker, type, and year. perPage maxes out at 50.

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=AVISO_AOS_ACIONISTAS&year=2024&perPage=20&field=dateRef&order=desc"

Each data[] item carries id (UUID), type, year, name, dateRef, and a nested company with tickers. Sorting by dateRef descending gives you the most recent notices first, which is what a payout tracker wants on every poll.

Persist the UUID, not the display name. Names come from the IPE feed as long Portuguese subject lines and are not stable identifiers.

Payout season: notices plus assembly minutes

Around annual meetings, pull both types in one request with the comma-separated types filter:

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&types=AVISO_AOS_ACIONISTAS,ATA_ASSEMBLEIA&year=2024&perPage=50"

For event monitoring that pairs payouts with material facts, swap in types=AVISO_AOS_ACIONISTAS,FATO_RELEVANTE. Pagination details (page, field, order) are in Paginate and filter CVM documents.

Step 3: Download the PDF

curl -OJ -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/<document-id>/file"

File download does not consume extraction credits. An empty list is usually a corpus gap for that issuer and year, not an unsupported type.

Example: Python

import os
import requests

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}

company = requests.get(
    f"{BASE}/v1/companies/resolve",
    params={"query": "PETR4", "by": "ticker"},
    headers=H,
    timeout=60,
)
company.raise_for_status()

docs = requests.get(
    f"{BASE}/v1/documents",
    params={
        "ticker": "PETR4",
        "type": "AVISO_AOS_ACIONISTAS",
        "year": 2024,
        "perPage": 20,
        "field": "dateRef",
        "order": "desc",
    },
    headers=H,
    timeout=60,
)
docs.raise_for_status()

for row in docs.json()["data"]:
    print(row["id"], row.get("dateRef"), row.get("name"))

Scaling to a watchlist is the same call in a loop over tickers, one page at a time — see Build a multi-ticker CVM filings watchlist.

Getting the numbers out of the notice

This is the part worth being explicit about: the API returns filing metadata and the original PDF. It does not return a parsed dividend field. There is no amountPerShare, no recordDate, no paymentDate in the response body — those values live inside the document.

Two ways to bridge that gap:

• Parse the PDF yourself after GET /v1/documents/:id/file
• On Pro, enqueue page-level markdown with POST /v1/document-text-extractions and let a model read the terms — extraction is asynchronous and reports back through an HTTPS callback, with no synchronous "return the text now" route and no job status endpoint

Free and Student keys get 403 FORBIDDEN on extraction. See Extract text from CVM PDFs and async callbacks for the full contract.

When to use sibling types instead

New to the API? Start from the CVM API overview or the getting started guide.

Current limitations

• Coverage depends on the ingestion sync — empty results can be a gap, not an API error
• No push feed for "a new notice arrived"; clients poll GET /v1/documents
• No structured payout fields — amounts and dates come from the PDF, not the JSON
• Do not expect real-time delivery; latency follows the sync pipeline
• /v1/document-prefixes does not catalog IPE section trees — IPE items are whole PDFs
• Demo routes do not expose IPE downloads beyond the VALE3 FRE demo scope

Next steps

• Read the API docs — full /v1 contract and error codes
• Get an API key — list and download across supported issuers
• IPE filing type overview — taxonomy and sibling types
• CVM API overview — where this fits in the broader API

Related guides

• IPE: Brazil Periodic Disclosures and Material Facts
• List Brazil Material Facts (Fatos Relevantes) via API
• List Brazil Assembly Minutes (Atas de Assembleia) via API
• List Brazil Market Communications via API
• Build a Multi-Ticker CVM Filings Watchlist