Brazil Asset Impairment Write-Down Disclosures API: Track Provisions from CVM Filings

The problem

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

1. Market data terminals — summarize reported and adjusted EPS. They rarely store the issuer’s regulatory PDF with the full note text.
2. Periodic packages — DFP, ITR, and FRE with explanatory notes on impairments, provisions, fair-value adjustments, and subsequent events. Essential for footnote math, but you still need ticker-first access and stable file IDs.
3. Event disclosures — fatos relevantes when a write-down or material provision change is announced outside the normal filing calendar, or when management pre-announces an accounting effect.

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 — scoped to impairment, provisions, and write-down workflows.

For a concrete DFP footnote walkthrough (ICMS reversal, divestiture effects), see RADL3 earnings quality analysis. This guide focuses on the API list-and-download pattern across event and periodic layers.

Which filing type carries impairment and write-down detail?

Brazilian issuers do not expose a dedicated type=IMPAIRMENT in the apicvm document list. Impairment and provision detail usually appears under:

Practical rule: poll FATO_RELEVANTE on watchlists ahead of earnings season, list latest ITR/DFP for the same ticker after results, then filter event rows by name keywords (impairment, reducao, redução, valor recuperavel, valor recuperável, provisao, provisão, write-down, writedown, perda, reversao, reversão, ajuste, non-recurring, nao recorrente, não recorrente) before downloading PDFs. After download, search PDF text for redução ao valor recuperável, teste de impairment, or note references to CPC 01 / IAS 36.

Issuer titles vary: retailers file long name tokens tied to quarterly performance; miners may bundle impairment language inside broader operational updates. Zero rows in a given year does not prove the issuer never recorded an impairment — see limitations below.

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. List periodic packages — GET /v1/documents with type=ITR or type=DFP and year
4. Scope with dateRef; sort with field=dateRef&order=desc
5. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
6. 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=RADL3&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 impairment-related event 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=RADL3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("impairment|reducao|redução|provisao|provisão|perda|reversao|reversão|valor_recuperavel|valor recuperável|write-down|writedown|ajuste"; "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 periodic impairment detail, list the latest quarterly package:

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

Then download the PDF and search notes — or follow extract CVM financial footnotes from DFP for a structured footnote workflow.

Step 3: Download a filing PDF

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

Download does not consume extraction credits.

Example: Python watchlist for impairment-related filings

Poll material facts across a research 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", "MGLU3", "CSNA3"]
YEAR = datetime.utcnow().year
IMPAIR_RE = re.compile(
    r"impairment|reducao|redução|provisao|provisão|perda|reversao|reversão|"
    r"valor.recuperavel|write-down|writedown|ajuste|nao.recorrente|não.recorrente",
    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 IMPAIR_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"IMPAIR {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 impairment disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. Pair event polling with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). For leverage-driven impairments, cross-check Brazil debt covenant disclosures API. For legal contingencies that drive provisions, see Brazil litigation disclosures API.

Current limitations

• Documents, not adjusted EPS — apicvm does not compute non-GAAP metrics or classify recurring vs one-off lines automatically.
• Keyword filters are heuristic — name tokens help; many impairments appear only inside periodic PDF notes without event-layer 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.

Next steps

• Read the API docs
• Get an API key
• Extract CVM financial footnotes from DFP — periodic note workflows

Related guides

• Brazil debt covenant disclosures API — refinancing and leverage on the event layer
• Brazil guidance outlook disclosures API — projection updates
• Track Brazil earnings season with the CVM filings API — seasonal ITR workflow
• Extract text from CVM PDFs for AI agents — async markdown extraction