Brazil Subsequent Events Disclosures API: Track Post-Balance-Sheet Events from CVM Filings

The problem

Post-period surveillance splits into four stacks that English search results often merge:

1. Market data terminals — show ex-dates and corporate-action flags. They rarely store the full regulatory PDF with the issuer’s eventos subsequentes note and management’s adjusting vs non-adjusting judgment.
2. Periodic packages — DFP and ITR rows with notas explicativas on events after the reporting date, plus reconciliation to amounts recognized if adjusting. You need ticker-first access and stable document.id, not a one-off portal download per name.
3. Reference form — FRE may reference litigation, M&A pipeline, or liquidity risks that crystallize as subsequent events in the next ITR.
4. Events — fatos relevantes when management discloses a post-balance-sheet item before the explanatory note is published.

Scraping the CVM portal works for one ticker and breaks on a diversified 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 — scoped to subsequent-events workflows.

For republication of corrected financials, cross-check Brazil financial restatement disclosures API. For dividend-only workflows, see Brazil dividend disclosures API. For M&A signed after quarter-end, see Brazil merger and acquisition disclosures API.

Which filing type carries subsequent-events language?

Brazilian issuers do not expose a dedicated type=SUBSEQUENT_EVENTS in the apicvm document list. Subsequent events usually appear under:

Practical rule: list DFP/ITR for the issuer and filter annex rows whose name contains Subsequente, Evento, Subsequent, or Explicativa. Pull the latest FRE for litigation and M&A context. Poll FATO_RELEVANTE with Portuguese and English tokens (evento subsequente, subsequent event, dividendo, aquisição, acquisition, ajuste, non-adjusting, litígio, refinanciamento). After download, search PDF text for eventos subsequentes, evento subsequente, subsequent event, ajustante, não ajustante, data do balanço, or após a data.

Issuer packaging varies: banks may fold subsequent events into general notes; industrial names may dedicate a short standalone note. Zero rows with a keyword filter does not mean no disclosure — broaden the list or open the latest explanatory-notes annex manually.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List periodic filings — GET /v1/documents with type=ITR or type=DFP and year
3. Narrow subsequent-events notes — name=Subsequente or name=Evento
4. List annual reference — GET /v1/documents with type=FRE
5. List post-period events — GET /v1/documents with types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO
6. Scope with dateRef; sort with field=dateRef&order=desc
7. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
8. 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 subsequent-events annexes on recent ITR packages

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=ITR&year=2025&perPage=50&field=dateRef&order=desc" \
  | jq '.data[] | select(.name | test("subsequente|subsequent|evento"; "i")) | {id, type, dateRef, name}'

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: Download the subsequent-events note PDF

DOC_ID=123456
curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/$DOC_ID/file" -o subsequent-events-note.pdf

Search the PDF locally for adjusting vs non-adjusting language and amounts. apicvm does not return pre-parsed eventType: adjusting fields.

Step 3: List post-period material facts

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50&field=dateRef&order=desc" \
  | jq '.data[] | select(.name | test("dividendo|aquisição|acquisition|litígio|refinanciamento|subsequente"; "i")) | {id, type, dateRef, name}'

Pair event polling with Brazil material facts monitoring API for generic diff loops.

Step 4: Pull FRE for risks that may become subsequent events

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=FRE&year=2025&perPage=10&field=dateRef&order=desc"

On the public demo (VALE3 only), swap the host path to /v1/demo/documents with the same query parameters for smoke tests.

Step 5: Watchlist poll (Python sketch)

import os, re, requests

BASE = os.environ["APICVM_URL"]
KEY = os.environ["APICVM_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
WATCH = ["PETR4", "VALE3", "ITUB4", "BBDC4"]
SE_EVENT_RE = re.compile(
    r"evento subsequente|subsequent event|dividendo|aquisição|acquisition|"
    r"litígio|refinanciamento|ajustante|não ajustante",
    re.I,
)
seen = set()

def list_events(ticker):
    r = requests.get(
        f"{BASE}/v1/documents",
        headers=HEADERS,
        params={
            "ticker": ticker,
            "types": "FATO_RELEVANTE,COMUNICADO_AO_MERCADO",
            "year": 2025,
            "perPage": 50,
            "field": "dateRef",
            "order": "desc",
        },
        timeout=60,
    )
    r.raise_for_status()
    return r.json().get("data") or []

for ticker in WATCH:
    for doc in list_events(ticker):
        if doc["id"] in seen:
            continue
        if not SE_EVENT_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"SE_EVENT {ticker} {doc['dateRef']} {doc['name'][:70]}")

Wire this into GitHub Actions CVM filings monitor. For NLP over downloaded PDFs, see extract text from CVM PDFs for AI agents.

Where subsequent-events disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. Pair note annex polling with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). When subsequent events imply substantial doubt, cross-check Brazil going concern disclosures API. When fair-value remeasurements appear as adjusting events, see Brazil fair value measurement disclosures API. For the broader Brazil financial data API pillar, treat subsequent-events notes as the post-period bridge between balance-sheet date and publication date.

Current limitations

• Documents, not parsed event taxonomy — apicvm does not return adjusting vs non-adjusting labels, automatic amounts, or CPC 24 classification.
• Title heuristics — name filters miss annexes with generic titles; some subsequent-events language lives only inside the PDF body.
• Polling, not push — no webhook when CVM publishes a new note package. 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.
• ITR disambiguation — Informações Trimestrais (CVM quarterly financials), not US income tax return software.

Next steps

• Read the API docs
• Get an API key
• Brazil financial restatement disclosures API — retifications vs explanatory subsequent-events notes

Related guides

• Extract CVM financial footnotes from DFP — deeper note extraction patterns
• Track Brazil earnings season with the CVM filings API — seasonal ITR workflow
• Extract text from CVM PDFs for AI agents — async markdown extraction