Brazil Fair Value Measurement Disclosures API: Track Level 1–3 Hierarchy and MTM from CVM Filings

The problem

Fair-value surveillance splits into four stacks that English search results often merge:

1. Market data terminals — show marks and adjusted EBITDA. They rarely store the full regulatory PDF with the issuer’s hierarquia de valor justo roll-forward or commodity MTM bridge.
2. Periodic packages — DFP and ITR rows with notas explicativas on financial instruments, biological assets, investment property, and derivatives. You need ticker-first access and stable document.id, not a one-off portal download per name.
3. Reference form — FRE carries the annual inventory of valuation methods, critical estimates, and risk factors tied to fair-value items.
4. Events — fatos relevantes when MTM or revaluation effects are material before the next periodic package.

Scraping the CVM portal works for one ticker and breaks on a diversified watchlist (agro, banks, 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 fair-value measurement workflows.

For impairment-specific write-downs, cross-check Brazil asset impairment write-down disclosures API. For CPC 47 / IFRS 15 revenue timing only, see Brazil revenue recognition disclosures API. For a real DFP footnote walkthrough on commodity MTM, see TTEN3 commodity MTM earnings quality.

Which filing type carries fair-value language?

Brazilian issuers do not expose a dedicated type=FAIR_VALUE in the apicvm document list. Fair-value measurement usually appears under:

Practical rule: list DFP/ITR for the issuer and filter annex rows whose name contains Nota, Instrumento, Financeiro, Valor justo, Fair, or Explicativa. Pull the latest FRE for valuation-method chapters. Poll FATO_RELEVANTE with Portuguese and English tokens (valor justo, fair value, hierarquia, Level 1, Level 2, Level 3, MTM, mark-to-market, derivativo, commodity, mensuração). After download, search PDF text for valor justo, nível 1, nível 2, nível 3, mensuração, mark-to-market, or fair value hierarchy.

Issuer packaging varies: banks concentrate fair value in financial-instrument notes; agro names may embed commodity MTM in COGS bridges. Zero rows with a keyword filter does not mean no fair-value disclosure — broaden the list or open the latest explanatory-notes annex manually.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List periodic filings — GET /v1/documents with type=ITR or type=DFP and year
3. Narrow fair-value notes — name=Instrumento or name=Valor
4. List annual reference — GET /v1/documents with type=FRE
5. List MTM events — GET /v1/documents with types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO
6. Scope with dateRef; sort with field=dateRef&order=desc
7. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
8. 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 financial-instrument annexes on recent ITR packages

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=TTEN3&type=ITR&year=2025&perPage=50&field=dateRef&order=desc" \
  | jq '.data[] | select(.name | test("instrumento|financeiro|valor justo|fair"; "i")) | {id, type, dateRef, name}'

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: Download the fair-value note PDF

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

Search the PDF locally for hierarchy tables and MTM bridges. apicvm does not return pre-parsed fairValueLevel: 3 fields.

Step 3: List MTM-related material facts

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=TTEN3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50&field=dateRef&order=desc" \
  | jq '.data[] | select(.name | test("valor justo|fair value|MTM|derivativo|commodity"; "i")) | {id, type, dateRef, name}'

Pair event polling with Brazil material facts monitoring API for generic diff loops.

Step 4: Pull FRE for valuation risk narrative

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

For section-level FRE extraction patterns, see FRE risk factors API section filter.

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

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 = ["TTEN3", "PETR4", "VALE3", "ITUB4"]
FV_EVENT_RE = re.compile(
    r"valor justo|fair value|hierarquia|level [123]|MTM|mark-to-market|"
    r"derivativo|commodity|mensura",
    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 FV_EVENT_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"FV_EVENT {ticker} {doc['dateRef']} {doc['name'][:70]}")

Wire this into GitHub Actions CVM filings monitor. For NLP over downloaded PDFs, see extract text from CVM PDFs for AI agents.

Where fair-value disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. Pair note annex polling with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). When fair-value swings tie to policy changes, cross-check Brazil accounting policy change disclosures API. When hedging dominates, see Brazil foreign exchange risk disclosures API. For headline DRE context, see Brazil income statement disclosures API. For the broader Brazil financial data API pillar, treat fair-value notes as the measurement judgment layer on top of periodic statements.

Current limitations

• Documents, not parsed hierarchy tags — apicvm does not return Level 1/2/3 labels, automatic MTM amounts, or roll-forward tables.
• Title heuristics — name filters miss annexes with generic titles; some fair-value language lives only inside the PDF body.
• Polling, not push — no webhook when CVM publishes a new note package. 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
• Brazil asset impairment write-down disclosures API — impairment vs recurring MTM

Related guides

• Extract CVM financial footnotes from DFP — deeper note extraction patterns
• Brazil segment reporting disclosures API — revenue mix by segment
• Track Brazil earnings season with the CVM filings API — seasonal ITR workflow
• Extract text from CVM PDFs for AI agents — async markdown extraction