Brazil Segment Reporting Disclosures API: Track Revenue Mix from CVM Filings

The problem

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

1. Market data terminals — show rebased segment revenue when vendors parse statements. They rarely store the issuer’s regulatory PDF with the full note text and reconciliation tables.
2. Periodic packages — DFP, ITR, and FRE with segment notes, geographic splits, and management narrative on mix shifts. Essential for modeling, but you still need ticker-first access and stable file IDs.
3. Event disclosures — fatos relevantes when a divestiture, merger of segments, or material change in reporting structure is announced outside the normal filing calendar.

Scraping the CVM portal works for one ticker and breaks on a diversified watchlist (banks, miners, consumer, agribusiness). 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 segment reporting and revenue mix workflows.

For company-specific FRE walkthroughs (commodity vs retail mix), see use cases such as TTEN3 segment mix. This guide focuses on the API list-and-download pattern across periodic and event layers.

Which filing type carries segment reporting detail?

Brazilian issuers do not expose a dedicated type=SEGMENT in the apicvm document list. Segment information usually appears under:

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 divestiture keywords, and pull FRE once per year for structural context. After download, search PDF text for informações por segmento, segmento operacional, or CPC 22 / IFRS 8 references.

Issuer titles vary: conglomerates file long name tokens; pure-play names may bury segment detail only inside note PDFs without event-layer keywords. Zero rows in a given year does not prove the issuer reports as a single segment — see limitations below.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List periodic packages — GET /v1/documents with type=ITR or type=DFP and year
3. Narrow annex rows — same endpoint with name prefix filters (see section name filters)
4. List event filings — GET /v1/documents with type=FATO_RELEVANTE
5. Scope with dateRef; sort with field=dateRef&order=desc
6. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
7. 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=ABEV3&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 (segment tables live here)

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=ABEV3&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 divestiture-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=ABEV3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("segmento|segment|desinvestimento|divest|reclassific|spin|carve"; "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 segment narrative and product lines, list the latest FRE:

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

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

Step 4: Download a filing PDF

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

Download does not consume extraction credits.

Example: Python watchlist for segment-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", "ABEV3", "TTEN3", "RADL3"]
YEAR = datetime.utcnow().year
SEG_RE = re.compile(
    r"segmento|segment|desinvestimento|divest|reclassific|spin.off|carve.out|"
    r"unidade.negocio|business.unit|mix.receita",
    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 SEG_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"SEG {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 segment disclosures sit in the filings stack

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 segment weakness drives write-downs, cross-check Brazil asset impairment write-down disclosures API. When mix shifts follow M&A, see Brazil merger and acquisition disclosures API.

Current limitations

• Documents, not parsed segment tables — apicvm does not return structured segment revenue rows or automatic rebasing when issuers change lines.
• Keyword filters are heuristic — name tokens help on the event layer; many segment 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.

Next steps

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

Related guides

• Brazil asset impairment write-down disclosures API — provisions and non-recurring items
• Access DFP and ITR notes by section name — annex filters before download
• Track Brazil earnings season with the CVM filings API — seasonal ITR workflow
• Extract text from CVM PDFs for AI agents — async markdown extraction