Brazil Tax Contingency Disclosures API: Track Provisions and Fiscal Disputes from CVM Filings

A Brazil tax contingency disclosures API in the research sense is not a tax compliance SaaS, an effective-rate calculator, or a live docket of Receita Federal cases. It is access to the CVM filings where Brazilian issuers disclose income tax expense, deferred taxes, and fiscal contingencies — explanatory notes in DFP and ITR (Informações Trimestrais, not US income tax returns), contingency inventories in FRE, and event PDFs when a tax assessment or settlement is material. 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 tax-related titles, and how this hub differs from generic litigation monitoring, FX and hedging notes, and related-party disclosures.

The problem

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

Market data terminals — sometimes show parsed effective tax rates. They rarely store the issuer’s regulatory PDF with the full contingency table and audit narrative.
Periodic packages — DFP, ITR, and FRE with income tax notes, deferred tax balances, and probability-weighted contingency lines (PIS/COFINS, ICMS, IRPJ/CSLL, municipal disputes). Essential for earnings-quality and credit work, but you still need ticker-first access and stable file IDs.
Event disclosures — fatos relevantes when a large tax assessment, settlement with the fisco, or court ruling on a fiscal case is disclosed outside the normal filing calendar.

Scraping the CVM portal works for one ticker and breaks on a diversified watchlist (retail, banks, oil, utilities). 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 tax provision and contingency workflows.

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

Which filing type carries tax and contingency detail?

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

`type`	Role in tax / contingency workflows
`ITR` / `DFP`	Periodic financials — income tax expense, deferred taxes, and contingency notes
`FRE`	Annual reference form — consolidated contingency tables and risk factors on fiscal exposure
`FATO_RELEVANTE`	Material fact when a tax assessment, settlement, or material court decision is disclosed
`COMUNICADO_AO_MERCADO`	Occasional market communication when tax-driven earnings revisions are announced

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 fiscal keywords, and pull FRE once per year for the full contingency inventory. After download, search PDF text for imposto de renda, tribut, PIS, COFINS, ICMS, contingência, autuação, perda provável, or CPC 32 / IAS 37 references.

Issuer titles vary: some banks file long name tokens; retailers may bury contingency tables only inside note PDFs without event-layer keywords. Zero rows in a given year does not prove the issuer has no tax 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=RADL3&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 (tax tables live here)

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=RADL3&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 tax-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("tribut|imposto|fiscal|PIS|COFINS|ICMS|IRPJ|CSLL|contingencia|contingência|autuação|autuacao"; "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 contingency inventory and fiscal 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 contingency sections — or follow what is FRE for field context.

Step 4: Download a filing PDF

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

Download does not consume extraction credits.

Example: Python watchlist for tax-related events

Poll material facts across a multi-sector watchlist. 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", "VALE3", "RADL3", "BBAS3", "ITUB4"]
YEAR = datetime.utcnow().year
TAX_RE = re.compile(
    r"tribut|imposto|fiscal|PIS|COFINS|ICMS|IRPJ|CSLL|"
    r"contingencia|contingência|autuação|autuacao|"
    r"perda.provável|perda.provavel|tax.liability",
    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 TAX_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"TAX {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 tax disclosures sit in the filings stack

Layer	Types	Tax / contingency relevance
Periodic	`ITR`, `DFP`	Income tax expense, deferred taxes, contingency notes
Reference	`FRE`	Consolidated contingency tables and fiscal risk factors
Events	`FATO_RELEVANTE`, `COMUNICADO_AO_MERCADO`	Material assessments, settlements, or court outcomes

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 tax disputes overlap with affiliate pricing, cross-check Brazil related party transaction disclosures API. When provisions interact with FX remeasurement, see Brazil foreign exchange risk disclosures API. For broad legal event monitoring beyond tax, use Brazil litigation disclosures API.

Current limitations

Documents, not parsed tax engines — apicvm does not return effective tax rates, probability-weighted provision totals, or automatic contingency roll-forwards.
Keyword filters are heuristic — name tokens help on the event layer; many contingency 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