List Brazil Market Communications (Comunicados ao Mercado) via API

The problem

Research and surveillance workflows treat market communications as first-class events:

• Clarifications after a material fact
• Operational or commercial updates that are not “material facts”
• Cross-checks against earnings decks and FRE narrative

The portal can surface those filings. It does not give agents a stable typed filter and a per-document UUID. Bulk open-data dumps help offline ETL; they are awkward for “give me PETR4 market communications for 2024 over HTTP.”

What “market communication” means here

In the apicvm contract, presentations filed as market communications are split out from generic comunicados:

This is not a literal SEC Form 8-K clone. The analogy helps orientation; taxonomy and filing cadence are Brazilian.

IPE-style documents are single PDFs. Section prefixes (GET /v1/document-prefixes) still apply only to DFP, ITR, and FRE.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List communications — GET /v1/documents?type=COMUNICADO_AO_MERCADO
3. Download the PDF — GET /v1/documents/:id/file
4. Optional (Pro): enqueue page-level markdown — POST /v1/document-text-extractions

Auth: Authorization: Bearer or X-API-Key.

Setup

export APICVM_KEY='apicvm_...'
export APICVM_URL='https://apicvm.dev'

Prefer the demo API only for VALE3 evaluation — demo download/markdown scope is FRE risk factors, not IPE types. For market communications, use a real key.

Step 1: Resolve the company

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/companies/resolve?query=PETR4&by=ticker"

Confirm cnpj and tickers[]. Ambiguous name queries return 409 AMBIGUOUS_RESULT with candidates — tighten with by=ticker or by=cnpj.

Step 2: List comunicados ao mercado

Filter by ticker, type, and year. perPage max is 50.

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=COMUNICADO_AO_MERCADO&year=2024&perPage=20&field=dateRef&order=desc"

Each data[] item includes id (UUID), type, year, name, dateRef, and nested company. Store the UUID before downloading — display names are often long Portuguese titles from the feed.

Event watchlist: communications + material facts

Use types (comma-separated) when the agent should see comunicados and material facts together:

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&types=COMUNICADO_AO_MERCADO,FATO_RELEVANTE&year=2024&perPage=50"

Need decks in the same pack? See List Brazil investor presentations via API — that filter is APRESENTACAO_INVESTIDORES, not this one.

For pagination patterns (page, field, order), see Paginate and filter CVM documents.

Step 3: Download the PDF

curl -OJ -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/<document-id>/file"

File download does not consume extraction credits. Empty list results can mean a corpus gap for that issuer/year — not that the type is unsupported.

Example: Python

import os
import requests

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}

company = requests.get(
    f"{BASE}/v1/companies/resolve",
    params={"query": "PETR4", "by": "ticker"},
    headers=H,
    timeout=60,
)
company.raise_for_status()

docs = requests.get(
    f"{BASE}/v1/documents",
    params={
        "ticker": "PETR4",
        "type": "COMUNICADO_AO_MERCADO",
        "year": 2024,
        "perPage": 20,
        "field": "dateRef",
        "order": "desc",
    },
    headers=H,
    timeout=60,
)
docs.raise_for_status()

for row in docs.json()["data"]:
    print(row["id"], row.get("dateRef"), row.get("name"))

Store the UUID, not the display name — names can be long subject lines from the IPE feed.

Optional: extract text for agents (Pro)

IPE filings are PDFs. If an agent needs searchable markdown, enqueue async extraction with an HTTPS callback — same contract as DFP/FRE. There is no synchronous “return full text now” route, and Student keys get 403 on extraction. Details: Extract text from CVM PDFs and async callbacks.

When to use sibling types instead

Many compliance workflows poll comunicados around a release window, then pull the related material fact. See compliance monitoring.

Current limitations

• Coverage depends on the ingestion sync — empty results can be a gap, not an API error
• Not a push/webhook feed for “new filing arrived”; clients poll GET /v1/documents
• Do not claim real-time delivery; latency follows the sync pipeline
• /v1/document-prefixes does not catalog IPE section trees — IPE items are whole PDFs
• Demo routes do not expose IPE download/markdown for evaluation beyond the VALE3 FRE demo scope

Next steps

• Read the API docs — full /v1 contract and error codes
• Get an API key — list and download across supported issuers
• IPE filing type overview — taxonomy and sibling types
• Getting started with the CVM filings API — resolve → list → download baseline

Related guides

• IPE: Brazil Periodic Disclosures and Material Facts
• List Brazil Material Facts (Fatos Relevantes) via API
• List Brazil Investor Presentations via API
• Monitor Brazil Regulatory Filings for Compliance