Brazil Pension and Post-Employment Benefit Disclosures API: Track Plan Obligations from CVM Filings

A Brazil pension benefit disclosures API in the research sense is not a government INSS portal, a payroll SaaS, or an actuarial valuation engine. It is access to the CVM filings where Brazilian issuers disclose post-employment benefit obligations, sponsored pension plans, and related litigation — explanatory notes in DFP and ITR (Informações Trimestrais, not US income tax returns), risk narratives in FRE, and event PDFs when a plan settlement or material revision is disclosed. apicvm lets you list those rows by ticker, download the original filing, and diff new document.id values on a credit or equity watchlist.

This guide shows which type values to query, keyword heuristics for pension-related titles, and how this hub differs from generic litigation monitoring, tax contingency notes, and debt covenant notices.

The problem

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

Market data terminals — sometimes show parsed pension expense or funding status. They rarely store the issuer’s regulatory PDF with the full actuarial assumptions and plan narrative.
Periodic packages — DFP, ITR, and FRE with post-employment benefit notes (CPC 33 / IAS 19 style), sponsored-plan descriptions, and balance-sheet liabilities. Essential for credit and earnings-quality work in banks, oil, and utilities, but you still need ticker-first access and stable file IDs.
Event disclosures — fatos relevantes when a large plan agreement, court outcome on a sponsored fund, or material revision to benefit terms 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 pension and post-employment benefit workflows.

For company-specific walkthroughs, see PETR4 material litigation including Petros contingencies. This guide focuses on the API list-and-download pattern across periodic and event layers.

Which filing type carries pension and benefit detail?

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

`type`	Role in pension / benefit workflows
`ITR` / `DFP`	Periodic financials — post-employment benefit expense, actuarial assumptions, plan assets and liabilities
`FRE`	Annual reference form — employee benefit policies, sponsored-plan risk factors, and related contingencies
`FATO_RELEVANTE`	Material fact when a plan settlement, court decision, or material revision is disclosed
`COMUNICADO_AO_MERCADO`	Occasional market communication when benefit-driven provisions affect earnings

Practical rule: list latest ITR/DFP for each ticker during 3Q ITR season, narrow annex rows with name filters for notes (notas, notes, explicativas), poll FATO_RELEVANTE for pension keywords, and pull FRE once per year for sponsored-plan narrative. After download, search PDF text for previd, pension, Petros, benefício, pós-emprego, pos-emprego, atuarial, actuarial, plano de benef, or CPC 33 / IAS 19 references.

Issuer titles vary: some banks file long name tokens; industrial names may bury actuarial tables only inside note PDFs without event-layer keywords. Zero rows in a given year does not prove the issuer has no benefit exposure — see limitations below.

How apicvm helps

Resolve the issuer — GET /v1/companies/resolve
List periodic packages — GET /v1/documents with type=ITR or type=DFP and year
Narrow annex rows — same endpoint with name prefix filters (see section name filters)
List event filings — GET /v1/documents with type=FATO_RELEVANTE
Scope with dateRef; sort with field=dateRef&order=desc
Download the PDF — GET /v1/documents/:id/file (no extraction credits)
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 quarterly filings for one ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=BBAS3&type=ITR&year=2025&perPage=10&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.

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

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

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

Combine with filter CVM filings by section name when your catalog uses English or abbreviated tokens.

Step 3: List pension-related material facts

Filename tokens on the CVM IPE feed are predictable enough for a first-pass filter:

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("previd|pension|Petros|beneficio|benefício|pós-emprego|pos-emprego|atuarial|actuarial|plano.de.benef"; "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.

For annual benefit policy and sponsored-plan risk narrative, list the latest FRE:

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

Then download the PDF and search employee-benefit sections — or follow what is FRE for field context.

Step 4: Download a filing PDF

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

Download does not consume extraction credits.

Example: Python watchlist for pension-related events

Poll material facts across a watchlist with sponsored-plan exposure (banks, oil, utilities). Persist seen in your database in production.

import os, time, requests, re
from datetime import datetime

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}
WATCH = ["PETR4", "BBAS3", "VALE3", "ELET3", "ITUB4"]
YEAR = datetime.utcnow().year
PENSION_RE = re.compile(
    r"previd|pension|Petros|beneficio|benefício|"
    r"pós-emprego|pos-emprego|atuarial|actuarial|"
    r"plano.de.benef|post.employment|defined.benefit",
    re.I,
)
seen = set()  # load from your store on startup

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

for ticker in WATCH:
    for doc in list_events(ticker):
        if doc["id"] in seen:
            continue
        if not PENSION_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"PENSION {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 pension disclosures sit in the filings stack

Layer	Types	Pension / benefit relevance
Periodic	`ITR`, `DFP`	Post-employment benefit expense, actuarial assumptions, plan balances
Reference	`FRE`	Sponsored-plan policies, benefit risk factors, related contingencies
Events	`FATO_RELEVANTE`, `COMUNICADO_AO_MERCADO`	Material plan settlements, court outcomes, or benefit revisions

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 pension disputes overlap with broad legal dockets, cross-check Brazil litigation disclosures API. When benefit provisions interact with fiscal contingencies, see Brazil tax contingency disclosures API. When leverage covenants reference benefit funding, see Brazil debt and covenant disclosures API.

Current limitations

Documents, not parsed actuarial engines — apicvm does not return funding ratios, discount-rate sensitivity, or automatic liability roll-forwards.
Keyword filters are heuristic — name tokens help on the event layer; many actuarial 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
Extract CVM financial footnotes from DFP — periodic note workflows

Ready to integrate?

Get an API key and start querying Brazilian CVM filings programmatically.

Read the API docs Get API key