Brazil Earnings Per Share Disclosures API: Track Basic and Diluted EPS from CVM Filings

The problem

EPS surveillance splits into four stacks that English search results often merge:

1. Market data terminals — show consensus EPS, price, and split-adjusted history. They rarely store the issuer’s regulatory PDF with the LPA básico / diluído table and the footnote on weighted-average shares.
2. Periodic packages — DFP and ITR rows with the DRE and notas explicativas on capital, treasury shares, and dilutive instruments. You need ticker-first access and stable document.id, not a one-off portal download per name.
3. Reference form — FRE carries share capital, treasury stock policy, and equity-compensation narrative that explains future dilution.
4. Events — fatos relevantes when bonus shares, buybacks, or capital increases are filed before the next ITR restates the denominator.

Scraping the CVM portal works for one ticker and breaks on a diversified watchlist (banks, utilities, consumer). 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 EPS and share-count workflows.

For full DRE and margin lines without EPS focus, cross-check Brazil income statement disclosures API. For bonificação events only, see Brazil bonus share disclosures API. For treasury repurchase notices, see Brazil share buyback disclosures API.

Which filing type carries EPS language?

Brazilian issuers do not expose a dedicated type=EPS in the apicvm document list. Earnings per share usually appears under:

Practical rule: list DFP/ITR for the issuer and filter annex rows whose name contains Resultado, Demonstração, LPA, Lucro, Ação, Explicativa, or DRE. Open the primary financial statements annex first — LPA often sits below net income. Pull the latest FRE for capital and compensation chapters. Poll FATO_RELEVANTE with Portuguese and English tokens (lucro por ação, LPA, EPS, diluído, diluted, ações em circulação, weighted average, bonificação, recompra, treasury). After download, search PDF text for lucro por ação, LPA básico, LPA diluído, ações em circulação, média ponderada, diluição, or earnings per share.

Issuer packaging varies: some banks print EPS only in consolidated notes; industrial names may embed share-count reconciliation in a capital note. Zero rows with a keyword filter does not mean no EPS disclosure — open the latest DRE 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 income-statement annexes — name=Resultado or name=Demonstração
4. List annual reference — GET /v1/documents with type=FRE
5. List capital 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 income-statement 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("resultado|demonstração|DRE|explicativa"; "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 DRE / EPS PDF

DOC_ID=123456
curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/$DOC_ID/file" -o income-statement-eps.pdf

Search the PDF locally for LPA tables and share-count reconciliations. apicvm does not return pre-parsed basicEps or dilutedEps fields.

Step 3: List capital events that move the denominator

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("bonificação|recompra|buyback|capital|LPA|lucro por ação"; "i")) | {id, type, dateRef, name}'

Pair event polling with Brazil share buyback disclosures API and Brazil bonus share disclosures API when the event layer is your primary signal.

Step 4: Pull FRE for capital and equity-compensation context

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

When dilution comes from plans rather than capital actions, cross-check Brazil stock-based compensation disclosures API. 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"]
EPS_EVENT_RE = re.compile(
    r"lucro por ação|LPA|EPS|diluíd|diluted|bonificação|recompra|buyback|"
    r"ações em circulação|capital social",
    re.I,
)
seen = set()

def list_capital_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_capital_events(ticker):
        if doc["id"] in seen:
            continue
        if not EPS_EVENT_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"EPS_CAPITAL {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 EPS disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. Pair DRE annex polling with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). When EPS moves because of post-balance-sheet dividends or deals, cross-check Brazil subsequent events disclosures API. For the broader Brazil financial data API pillar, treat EPS notes as the per-share bridge between net income and what equity holders actually earn per share.

Current limitations

• Documents, not parsed EPS — apicvm does not return basic/diluted EPS numbers, weighted-average share counts, or automatic dilution math.
• Title heuristics — name filters miss annexes with generic titles; some LPA tables live only inside the PDF body.
• Polling, not push — no webhook when CVM publishes a new ITR 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 income statement disclosures API — full DRE and margin workflows

Related guides

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