Brazil Litigation Disclosures API: Track Legal Proceedings and Contingency Notices from CVM Filings

The problem

Brazilian legal-risk monitoring splits into three stacks that English search results often merge:

1. Court and news databases — dockets, journalist summaries, and third-party case trackers. Useful for context, not always aligned with what the issuer filed with CVM.
2. Periodic inventories — contingency tables and risk-factor chapters in FRE, DFP, and ITR. Essential for exposure sizing, but they lag new developments until the next filing cycle.
3. Event disclosures — fatos relevantes when a large judgment, settlement, or procedural milestone is disclosed, plus occasional comunicados ao mercado when issuers frame legal news for the market.

Scraping the CVM portal works for one ticker and breaks on a multi-name 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 — the same pattern as Brazil material facts monitoring API, scoped to legal proceedings and contingencies.

For deep FRE-only diligence examples, see issuer use cases such as PETR4 material litigation contingencies or BBAS3 judicial risk factors. This guide focuses on the event API layer.

Which filing type carries litigation updates?

Brazilian issuers do not expose a dedicated type=LITIGATION in the apicvm document list. Legal events usually surface under:

Practical rule: poll FATO_RELEVANTE on active watchlists, add COMUNICADO_AO_MERCADO when your issuer habitually files legal news there, then filter rows by name keywords (processo, contingencia, contingência, acordo, sentenca, sentença, litigio, litígio, Reivindicacao, reivindicação, arbitragem, indenizacao, indenização, recuperacao, recuperação) before downloading PDFs. After download, search PDF text for processo judicial, acordo de leniência, or perda provável.

Issuer titles vary: miners may file Reivindicacao updates while banks file Processo or Contingencias. Zero rows in a given year does not prove no litigation occurred — see limitations below.

Concrete example (demo corpus): VALE3 listed a 2025-11-14 material fact whose name includes Reivindicacao_do_Reino_Unido — a regulatory update on an international claim, not a generic earnings projection.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List event filings — GET /v1/documents with type=FATO_RELEVANTE (optionally add COMUNICADO_AO_MERCADO)
3. Scope with year and optional dateRef; sort with field=dateRef&order=desc
4. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
5. 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 material facts for one ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=FATO_RELEVANTE&year=2025&perPage=50&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 litigation-related rows

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=VALE3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("processo|contingencia|contingência|acordo|sentenca|sentença|litigio|litígio|Reivindicacao|reivindicação|arbitragem|indenizacao|indenização|recuperacao|recuperação"; "i")) | {id, type, dateRef, name}'

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

After download, search PDF text for valor da causa or perda remota for validation. Extraction credits apply only if you use the text-extraction endpoint.

Step 3: Download a litigation notice PDF

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

Download does not consume extraction credits.

Example: Python watchlist for litigation filings

Poll material facts across a legal-risk 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", "BBAS3", "ITUB4", "ABEV3"]
YEAR = datetime.utcnow().year
LIT_RE = re.compile(
    r"processo|contingencia|contingência|acordo|sentenca|sentença|"
    r"litigio|litígio|reivindicacao|reivindicação|arbitragem|"
    r"indenizacao|indenização|recuperacao|recuperação",
    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 LIT_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"LIT {ticker} {doc['dateRef']} {doc['name'][:70]}")

Wire this into GitHub Actions 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 litigation updates sit in the filings stack

Brazil regulatory filings API explains the full layer map. For background on material facts demand, see What is a fato relevante? and the pillar CVM API.

Current limitations

• Documents, not court dockets — apicvm does not integrate with tribunals or unified national case databases.
• Keyword filters are heuristic — name tokens help; false negatives are possible if issuers use unusual titles.
• 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.

Next steps

• Read the API docs
• Get an API key
• Brazil reference form API — FRE contingency inventory layer

Related guides

• Brazil material facts monitoring API — generic fato relevante poll loop
• Brazil management change disclosures API — leadership events
• Brazil merger and acquisition disclosures API — deal-driven legal risk
• Extract text from CVM PDFs for AI agents — async markdown extraction