Bulk CVM ZIP Downloads vs Per-Filing API Access

Researchers often start with CVM bulk downloads — monthly ZIP archives and CSV indexes from the open-data portal (dados.cvm.gov.br). That works for one-time academic datasets. Product teams building ticker-first workflows face a different question: bulk CVM download vs API — which fits your pipeline?

This page compares bulk ingestion with apicvm's per-filing REST API so you can choose based on workflow, not habit.

What bulk CVM downloads provide

Typical bulk workflow:

Download ZIP/CSV from dados.cvm.gov.br
  → Extract locally
  → Parse metadata tables (CNPJ-centric)
  → Join to ticker universe (your problem)
  → Store files in object storage
  → Re-download when CVM updates archives

Pros:

Free and complete for historical research snapshots
Good for offline batch analysis (single machine, Jupyter, thesis)
No API key or subscription

Cons:

Challenge	Impact
CNPJ-centric indexing	You map CNPJ → B3 ticker yourself
Archive lag	Updates when CVM publishes new ZIPs, not per-filing
No per-document HTTP download	Hard to fetch one PETR4 DFP 2024 PDF on demand
Storage and ETL overhead	Full corpus replication on your infra
No text extraction	PDF parsing is your job

What apicvm per-filing API provides

GET /v1/companies/resolve?query=PETR4
  → GET /v1/documents?ticker=PETR4&type=DFP&year=2024
  → GET /v1/documents/:id/file
  → POST /v1/document-text-extractions (optional)

Pros:

Ticker-first filters — PETR4, ITUB4, BBAS3
Stable document UUIDs for citation and deduplication
Paginated list with type, year, dateRef filters
Async page-level markdown extraction via callback
Versioned /v1 contract — no HTML scraping

Cons:

Subscription and rate limits per API key
Corpus covers ingested companies — not a full CVM mirror on day one
Not designed for one-shot full-corpus replication

When to use each

Scenario	Bulk ZIP	apicvm API
Academic dataset of all CVM filings 2010–2020	✅	❌
App: "Show latest ITR for user's watchlist"	❌	✅
AI agent answering questions about one company	❌	✅
One-time CSV join on CNPJ for econometrics	✅	Optional
Production pipeline with ticker filters	❌	✅
Need page-level text for RAG	❌	✅

Hybrid approach

Many teams use both:

Bulk for historical backfill and macro research
API for incremental updates, user-facing features, and agent tools

apicvm ingests from the same CVM sources — you do not need to replicate bulk storage if your product queries by ticker.

Example: same task, two paths

Goal: Get PETR4 DFP filings for 2024.

Bulk path: Download annual document index CSV → filter by CNPJ 33000167000101 → locate file URLs → download PDFs manually or script against archive structure.

API path:

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

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

Pick document.id from results → download or extract.

Current limitations

apicvm does not ship bulk ZIP exports — use open data for that.
Bulk downloads do not include apicvm's text extraction or ticker resolution.
Coverage and freshness differ; evaluate against your specific tickers.

Next steps

Ready to integrate?

Get an API key and start querying Brazilian CVM filings programmatically.

Read the API docs Get API key