Brazil Guidance Outlook Disclosures API: Track Projection Updates from CVM Material Facts

The problem

Equity and credit teams track three layers that English search results often conflate:

1. Market estimates — consensus databases and broker models. They summarize expectations; they are not the issuer’s regulatory disclosure.
2. Periodic packages — ITR and DFP with audited or reviewed financials and management discussion. They refresh on a calendar, not the day management revises iron-ore volume or sugar crush guidance.
3. Event guidance — fatos relevantes (and sometimes investor decks) when a listed company updates projeções, outlook, or operational targets that can move the stock before the next quarterly filing.

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 guidance and outlook revisions.

For deep FRE-only projection tables (mining or agribusiness), see use cases such as VALE3 production guidance in FRE. This guide focuses on the event API layer.

Which filing type carries guidance updates?

Brazilian issuers do not expose a dedicated type=GUIDANCE in the apicvm document list. Outlook revisions usually surface under:

Practical rule: poll FATO_RELEVANTE on active watchlists, add APRESENTACAO_INVESTIDORES during earnings weeks, then filter rows by name keywords (projecao, projeção, projecoes, projeções, outlook, guidance, previsao, previsão, meta, target, volume, producao, produção, EBITDA, capex, CapEx) before downloading PDFs. After download, search PDF text for projeção de produção, guidance, or outlook.

Issuer titles vary: miners file atualizacao_de_projecoes while banks may use previsao in a market communication. Zero rows in a given year does not prove the issuer never revised guidance — see limitations below.

Concrete example (demo corpus): VALE3 listed a 2025-12-02 material fact whose name includes atualizacao_de_projecoes — a projection update, not a dividend or litigation notice (demo API, queried 2026-09-21).

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List event filings — GET /v1/documents with type=FATO_RELEVANTE (optionally add APRESENTACAO_INVESTIDORES,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 guidance-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("projecao|projeção|projecoes|projeções|outlook|guidance|previsao|previsão|atualizacao_de_projecoes|meta|target|producao|produçã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 projeção, guidance, or outlook to validate the row. Extraction credits apply only if you use the text-extraction endpoint.

Step 3: Download a guidance update PDF

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

Download does not consume extraction credits.

Example: Python watchlist for guidance filings

Poll material facts across a model 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", "WEGE3", "SUZB3", "ABEV3"]
YEAR = datetime.utcnow().year
GUIDANCE_RE = re.compile(
    r"projecao|projeção|projecoes|projeções|outlook|guidance|"
    r"previsao|previsão|atualizacao_de_projecoes|meta|target|"
    r"producao|produção|capex|ebitda",
    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,APRESENTACAO_INVESTIDORES",
            "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 GUIDANCE_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"GUIDANCE {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 guidance updates sit in the filings stack

Brazil regulatory filings API explains the full layer map. During ITR windows, pair this hub with Track Brazil earnings season for scheduled packages plus event filings. For background on material facts demand, see What is a fato relevante? and the pillar CVM API.

Current limitations

• Documents, not consensus — apicvm does not store broker estimates or Bloomberg consensus fields.
• 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 quarterly earnings ITR monitoring — periodic financial layer

Related guides

• Brazil material facts monitoring API — generic fato relevante poll loop
• Track Brazil earnings season with the CVM API — ITR + presentations cadence
• Brazil dividend disclosures API — corporate actions on the event layer
• Extract text from CVM PDFs for AI agents — async markdown extraction