List Brazil Formulário de Referência (FRE) via API

The problem

English IR pages often call the Formulário de Referência "similar to a 10-K." That analogy is only half right. A US 10-K mixes audited statements with Item 1 / 1A / 7. In Brazil the audited numbers live in DFP. The handbook — history, risks, board, pay — lives in FRE. Point form=10-K at this API and you get nothing useful.

Two more traps:

• Multi-market aggregators sometimes relabel Brazilian annual packages as 10-K. That label is theirs. apicvm stores the native type: FRE for the narrative bundle, DFP for the statements.
• Form 20-F is an SEC filing for some Brazilian ADR issuers. apicvm does not host 20-F PDFs. Use EDGAR for that trail; use type=FRE for the CVM text.

FRE is also a bundle, not one PDF. A large issuer can file seventy-plus section files in a year. Downloading every row, or running markdown extraction on the whole catalog, is the expensive way to answer one question.

FRE vs the rest of the 10-K mental model

CVM is Brazil's securities regulator. Resolve, list, and fetch still look like an EDGAR client. The type codes do not. Do not treat the table below as an official SEC mapping.

dateRef on an FRE row is typically the reference year-end (for example 2025-12-31). Companies update FRE annually and when material facts change, so a year can contain restated section files.

How apicvm helps

1. Optional: try the public demo — GET /v1/demo/documents (VALE3 only, no key)
2. Resolve the issuer — GET /v1/companies/resolve
3. List the FRE bundle — GET /v1/documents?type=FRE
4. Discover section prefixes — GET /v1/document-prefixes?type=FRE
5. Download the PDF — GET /v1/documents/:id/file
6. Optional (Pro): enqueue page-level markdown — POST /v1/document-text-extractions

Auth on /v1 (not demo): Authorization: Bearer or X-API-Key.

Try without a key (VALE3)

The public demo API is scoped to Vale (VALE3, CNPJ 33592510000154). Download and cached markdown are limited to FRE 2025 files whose name starts with DescricaoFatoresRisco. Demo perPage maxes out at 20. No Authorization header.

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

curl "$APICVM_URL/v1/demo/companies/resolve?query=VALE3&by=ticker"

curl "$APICVM_URL/v1/demo/documents?ticker=VALE3&type=FRE&year=2025&name=DescricaoFatoresRisco&perPage=5"

Pick an id from data[], then:

curl -OJ "$APICVM_URL/v1/demo/documents/<document-id>/file"
curl "$APICVM_URL/v1/demo/documents/<document-id>/markdown"

Resolving PETR4 on /v1/demo/* returns 403 FORBIDDEN. File and markdown routes reject FRE sections outside that risk-factor prefix. Async extraction (POST /v1/document-text-extractions) is not on the demo. Rate limits apply per IP (30 req/min, 200 req/UTC day).

Setup (authenticated)

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

Use a real key for PETR4, other tickers, other FRE years, and sections other than Vale's 2025 risk factors.

Step 1: Resolve the company

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

Confirm cnpj and tickers[] before you store anything. A name query that matches more than one issuer returns 409 AMBIGUOUS_RESULT with candidates. Tighten it with by=ticker or by=cnpj.

Step 2: List FRE filings

Filter by ticker, type, and year. Authenticated perPage maxes out at 50. PETR4's 2025 FRE in the ingested corpus is 78 section files with dateRef=2025-12-31 — more than one page.

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

Each data[] item carries id (UUID), type, year, name, dateRef, and a nested company with tickers. Persist the UUID. Display names are long Portuguese section titles and are not stable identifiers.

Empty data for a large issuer is usually a corpus gap for that year, not an unsupported type. Mid-year FRE for the current calendar year can look thin until the annual update is ingested.

Narrow the bundle by name

Do not download all 78 files to read risk factors or board composition. Prefixes for FRE (and DFP / ITR) come from:

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/document-prefixes?type=FRE"

The response is { "data": ["...", "..."] } — distinct name prefixes in the ingested corpus. Pass a partial name on the documents list. On PETR4 FRE 2025 these prefixes are present:

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=FRE&year=2025&name=DescricaoFatoresRisco&perPage=20"

Same pattern for issuer history (HistoricoEmissor), board (InformacoesConselhoAdm), and compensation policy (PoliticaPraticaRemuneracao). Partial match works: name=DescricaoFatoresRisco matches DescricaoFatoresRisco-4_1 and longer certified variants.

More on this pattern: Filter CVM filings by section name and Fetch FRE risk factors without the full filing. Pagination details are in Paginate and filter CVM documents.

Need the audited statements for the same year? See List Brazil DFP filings (10-K equivalent): type=DFP. For interims, List Brazil ITR filings (10-Q equivalent): type=ITR (Informações Trimestrais, not income tax).

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. The bytes are the original filing (usually application/pdf), not parsed governance objects or XBRL.

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": "FRE",
        "year": 2025,
        "name": "DescricaoFatoresRisco",
        "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"))

A watchlist is the same call in a loop over tickers, one page at a time. See Build a multi-ticker CVM filings watchlist.

Getting text out of the FRE

The list endpoint returns metadata and the original PDF. It does not return a JSON schema of risk factors, directors, or pay. Original filings are in Portuguese.

Two ways to go further:

• Parse the PDF yourself after GET /v1/documents/:id/file
• On Pro, enqueue page-level markdown with POST /v1/document-text-extractions. Extraction is asynchronous: you get 202 immediately, progress arrives on an HTTPS callback_url, and there is no job-status GET. Cache hits still debit one credit per page. Free and Student keys receive 403 FORBIDDEN.

See Extract text from CVM PDFs and async callbacks. The demo's GET /v1/demo/documents/:id/markdown is cached Vale risk-factor text only — it is not the Pro extraction job.

If you want bulk CSV across many issuers for a one-off academic load, CVM open data ZIP dumps (cia_aberta-doc-fre) may be a better fit than per-ticker HTTP. That comparison is in CVM open data vs apicvm.

For the mapping across the whole CVM set, see Brazil CVM vs SEC EDGAR. Definition and typical sections: What is FRE?. New to the product API? CVM API overview.

Current limitations

• GET /v1/documents does not accept type=10-K or type=20-F. Use FRE for the CVM reference form.
• Coverage depends on the ingestion sync. Empty results can be a gap, not an API error.
• No push feed for "a new FRE section arrived"; clients poll GET /v1/documents.
• No structured governance or compensation objects in the JSON. The narrative is inside the PDF.
• Do not expect real-time delivery; latency follows the sync pipeline.
• Demo routes do not expose FRE downloads beyond VALE3 FRE 2025 DescricaoFatoresRisco.
• apicvm covers Brazilian CVM filings only. It does not replace EDGAR for US issuers or Form 20-F.

Next steps

• Read the API docs — full /v1 contract and error codes
• Get an API key — list and download FRE beyond the Vale demo
• What is FRE? — what the form contains
• CVM API overview — where FRE sits next to DFP, ITR, and IPE

Related guides

• What is FRE? Formulário de Referência
• Brazil CVM vs SEC EDGAR
• List Brazil DFP filings (10-K equivalent)
• List Brazil ITR filings (10-Q equivalent)
• Try the apicvm demo API with VALE3
• Fetch FRE risk factors without the full filing
• FRE: Brazil's Reference Form