Brazil Related Party Transaction Disclosures API: Track Affiliate Deals from CVM FRE and Material Facts

The problem

Brazilian related-party diligence splits into three stacks that English search results often merge:

1. IR and data vendors — narrative summaries and structured feeds. Useful for screening, not always aligned with the exact PDF filed with CVM.
2. Periodic reference form — the annual FRE bundle includes a dedicated related-party section (prefix PercentualPartesRelacionadas). Essential for policy and transaction tables, but it updates on the FRE cycle, not on every affiliate loan.
3. Event disclosures — fatos relevantes when a material related-party transaction, guarantee, or restructuring is disclosed between FRE updates.

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 — the same pattern as Brazil reference form API, scoped to related parties.

For a broader FRE governance pull (board + pay + related parties in one job), see FRE governance and compensation sections API. This guide focuses on the related-party disclosure workflow and conversion path to production keys.

Which filing type carries related-party disclosures?

Brazilian issuers do not expose a dedicated type=RELATED_PARTY in the apicvm document list. Related-party content usually surfaces under:

Practical rule: start with FRE and name=PercentualPartesRelacionadas for the structured section. Poll FATO_RELEVANTE on active watchlists when you need event coverage, filtering name for tokens such as parte relacionada, partes relacionadas, controlador, coligada, afiliada, transacao, transação, mutuo, mútuo, garantia, cessao, cessão.

Issuer naming varies. Zero rows in a given year does not prove no related-party exposure — see limitations below.

Concrete example (demo corpus): VALE3 lists PercentualPartesRelacionadas-8_17 for reference year 2025 (dateRef 2025-12-31) via the demo API (queried 2026-09-20).

Discover valid FRE prefixes with GET /v1/document-prefixes?type=FRE — the demo corpus includes PercentualPartesRelacionadas.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List FRE sections — GET /v1/documents with type=FRE and name=PercentualPartesRelacionadas
3. Optional events — GET /v1/documents with type=FATO_RELEVANTE (and optionally COMUNICADO_AO_MERCADO)
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 the FRE related-party section

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

Response rows include stable id, dateRef, name, and nested company metadata. Use id as your cache key.

On the public demo (no key):

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

Step 2: Download the related-party PDF

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

Download does not consume extraction credits.

Step 3: Optional — scan material facts for related-party keywords

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("parte.?relacionada|partes.?relacionadas|controlador|coligada|afiliada|transac|mutuo|mútuo|garantia|cessao|cessão"; "i")) | {id, type, dateRef, name}'

After download, search PDF text for política de transações com partes relacionadas or valor envolvido for validation.

Example: Python watchlist for FRE related-party sections

Refresh the FRE section yearly per ticker, and optionally poll events weekly.

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", "ITUB4", "BBDC4", "WEGE3"]
YEAR = datetime.utcnow().year
RP_RE = re.compile(
    r"parte.?relacionada|partes.?relacionadas|controlador|coligada|afiliada|"
    r"transac|mutuo|mútuo|garantia|cessao|cessão",
    re.I,
)
seen = set()

def list_docs(ticker, **params):
    r = requests.get(f"{BASE}/v1/documents", headers=H, params={"ticker": ticker, **params})
    if r.status_code == 429:
        time.sleep(5)
        return list_docs(ticker, **params)
    r.raise_for_status()
    return r.json()["data"]

for ticker in WATCH:
    for doc in list_docs(ticker, type="FRE", year=YEAR, name="PercentualPartesRelacionadas", perPage=50):
        print(f"FRE-RP {ticker} {doc['dateRef']} {doc['name']}")

    for doc in list_docs(
        ticker,
        types="FATO_RELEVANTE,COMUNICADO_AO_MERCADO",
        year=YEAR,
        perPage=50,
        field="dateRef",
        order="desc",
    ):
        if doc["id"] in seen:
            continue
        if not RP_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"EVENT-RP {ticker} {doc['dateRef']} {doc['name'][:70]}")

Wire this into GitHub Actions or extend the diff pattern from Brazil material facts monitoring API. For section-prefix discovery, see filter CVM filings by section name.

Where related-party disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. For FRE background and demand context, see What is FRE? and analyze Brazil FRE governance risks.

Current limitations

• Documents, not a contract registry — apicvm does not maintain a live graph of affiliate agreements outside filed PDFs.
• Keyword filters are heuristic — event-layer name tokens help; false negatives are possible if issuers use unusual titles.
• Polling, not push — no webhook when CVM publishes a new filing. 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 reference form API — full FRE bundle workflow

Related guides

• Filter CVM filings by section name — prefix patterns for FRE, DFP, ITR
• Brazil material facts monitoring API — generic fato relevante poll loop
• Brazil management change disclosures API — leadership events (often adjacent in governance screens)
• Extract text from CVM PDFs for AI agents — async markdown extraction