Brazil Stock-Based Compensation Disclosures API: Track RSU and Option Plans

The problem

Equity pay surveillance splits into three stacks that English search results often merge:

1. Market data terminals — sometimes show parsed share count or basic SBC expense. They rarely store the issuer’s regulatory PDF with vesting rules, strike mechanics, and board approval narrative.
2. Periodic packages — DFP, ITR, and FRE with CPC 10 / IFRS 2 style share-based payment notes, FRE section 8.4 equity plans, and compensation committee disclosures. Essential for proxy and earnings-quality work, but you still need ticker-first access and stable file IDs.
3. Event disclosures — fatos relevantes when a new long-term incentive plan, extraordinary grant, or plan amendment is disclosed outside the normal filing calendar.

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 stock-based compensation workflows.

For company-specific walkthroughs, see FRE governance compensation sections or PGMN3 executive bonus and share-based pay on FRE. This guide focuses on the API list-and-download pattern across periodic and event layers.

Which filing type carries equity incentive detail?

Brazilian issuers do not expose a dedicated type=RSU in the apicvm document list. Equity pay detail usually appears under:

Practical rule: pull FRE once per year with a name filter for PlanoRemuneracaoBaseadoAcoes (see filter CVM filings by section name), list latest ITR/DFP during 3Q ITR season, narrow annex rows with name filters for notes (notas, notes, explicativas), and poll FATO_RELEVANTE for equity keywords. After download, search PDF text for opcao, opção, RSU, stock, acao, ação, remuneracao, remuneração, equity, dilui, vesting, or CPC 10 / IFRS 2 references.

Issuer titles vary: some names bury grant tables only inside note PDFs without event-layer keywords. Zero rows in a given year does not prove the issuer has no equity plan — see limitations below.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List periodic packages — GET /v1/documents with type=ITR or type=DFP and year
3. Pull FRE equity plan section — GET /v1/documents with type=FRE and name=PlanoRemuneracaoBaseadoAcoes
4. List event filings — GET /v1/documents with type=FATO_RELEVANTE
5. Scope with dateRef; sort with field=dateRef&order=desc
6. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
7. 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 FRE equity plan section for one ticker

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

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.

Step 2: Narrow to explanatory notes (SBC tables live here)

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=WEGE3&type=ITR&year=2025&perPage=50&name=Notas" \
  | jq '.data[] | {id, type, dateRef, name}'

Combine with access DFP and ITR notes by section name when your catalog uses English or abbreviated tokens.

Step 3: List equity-related material facts

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PGMN3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("opcao|opção|RSU|stock|acao|ação|remuneracao|remuneração|equity|incentivo|plano de acoes|plano de ações"; "i")) | {id, type, dateRef, name}'

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

Step 4: Download the filing PDF

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

Store document.id in your warehouse. Re-download when the issuer replaces a filing; do not assume name alone is a stable key.

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 = ["WEGE3", "PGMN3", "RADL3", "ITUB4"]
EQUITY_RE = re.compile(
    r"opcao|opção|RSU|stock|acao|ação|remuneracao|remuneração|equity|incentivo|plano de ac",
    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 EQUITY_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"EQUITY {ticker} {doc['dateRef']} {doc['name'][:70]}")

Wire this into GitHub Actions CVM filings monitor or extend the diff pattern from Brazil material facts monitoring API. For NLP over downloaded PDFs, see extract text from CVM PDFs for AI agents.

Where equity pay disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. Pair periodic note pulls with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). When grants involve affiliates, cross-check Brazil related party transaction disclosures API. When board turnover coincides with plan redesign, see Brazil management change disclosures API. When equity pay sits next to post-employment benefits, see Brazil pension benefit disclosures API.

Current limitations

• Documents, not parsed cap tables — apicvm does not return fully diluted share count, automatic grant fair value, or vesting schedules parsed from tables.
• Keyword filters are heuristic — name tokens help on the event layer; many CPC 10 tables appear only inside periodic PDF notes without matching keywords.
• Polling, not push — no webhook when CVM publishes a new fact. 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
• Filter CVM filings by section name — FRE compensation chapters

Related guides

• Brazil pension benefit disclosures API — post-employment benefit notes
• Brazil management change disclosures API — CEO and director appointments
• Access DFP and ITR notes by section name — annex filters before download
• Track Brazil earnings season with the CVM filings API — seasonal ITR workflow
• Extract text from CVM PDFs for AI agents — async markdown extraction