# Beneficial Ownership (13D/13G) — New — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 587853af
> Fetch this file at: https://uat.finradarapi.com/llms/beneficial-ownership-13d-13g-new.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## Beneficial Ownership (13D/13G) — New

Comprehensive beneficial ownership API with normalized multi-table data model. Supports multi-filer group filings, purpose classification, amendment tracking with threshold crossing detection, and unified holder identity linking across Form 4, 13F, and 13D/G. Response fields include: cusip (array), nameOfIssuer, titleOfSecurities, eventDate, secFilingUrl, entities (array from SGML index with name/cik/irsNo/sic), groupMembers (array for group filings), signatures, applicableRule (13G), footnotes. Filer objects include: entityType (entity/individual), citizenship, principalOccupation, employerName, legalProceedingsDisclosureRequired (boolean), per-filer footnotes. Position objects include: sourceOfFunds (array), typeOfReportingPerson (array), amountOfFunds, amountExcludesCertainShares, indirectOwnershipExplanation, sharesAcquirable60Days.

### GET /api/v1/ownership/beneficial-ownership/filings

List and filter beneficial ownership filings with full structured data.

**Token cost:** 10 tokens per call

**Response fields:**
- `filings` (array): Array of filing rows — one row per `(accession_number, filer_cik)` pair (so a 13D filed jointly by 3 group members produces 3 rows). Sorted per the `sort` + `order` parameters. Empty array on no match.
- `filings[].accessionNumber` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `/ownership/beneficial-ownership/filings/{accession}` to retrieve the full structured payload (all filers + positions + exhibits + amendment chain).
- `filings[].formType` (string): Schedule 13D/13G form type — one of `13D` (active intent — 10-day filing window after crossing 5%), `13G` (passive intent — annual filing), `13D/A` (13D amendment), `13G/A` (13G amendment). The `/A` suffix is preserved verbatim. 13D filings carry materially higher signal than 13G — they require disclosing INTENT, not just OWNERSHIP.
- `filings[].filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance. Distinct from `eventDate` (the date that triggered the filing obligation — typically the date the position crossed 5%). For activist surveillance, the `filedAt` lag from `eventDate` is itself a signal (close-to-deadline filings indicate compliance-heavy intent vs proactive disclosure).
- `filings[].issuerCik` (string): Issuer CIK (the company being reported on, NOT the filer). 10-character zero-padded string. The natural join key against `/api/v1/sec/filings`, `/financials/metrics`, and `/insider-module/api/insiders/transactions/by-ticker/{ticker}`.
- `filings[].issuerTicker` (string (nullable)): Issuer ticker resolved from the issuer CIK via `ticker_norm_aliases`. Null when the issuer has no public-equity ticker (private-company 13D filings against pending mergers, foreign issuers without ADRs). Multi-class issuers return the canonical class (typically the most-traded one).
- `filings[].nameOfIssuer` (string): Issuer name AS FILED on the cover page (typically all-caps in EDGAR convention). Casing preserved verbatim — for canonical company name use the Sharadar SF1 lookup via the issuer CIK.
- `filings[].filerCik` (string): Filer CIK (the entity DOING the reporting — fund, family office, individual, or activist). 10-character zero-padded string. Join key for filer-portfolio queries via `/ownership/beneficial-ownership/filers/{cik}/portfolio`.
- `filings[].filerName` (string): Filer name AS FILED (typically all-caps EDGAR convention). For activists this often surfaces multi-entity structures (e.g. `ICAHN CARL C`, `ICAHN ENTERPRISES LP`, `ICAHN PARTNERS LP` — all Carl Icahn affiliates). Use `filerCik` as the stable identifier.
- `filings[].percentOfClass` (number (nullable)): Aggregate beneficial-ownership percent of the issuer's voting class, as reported by the filer (Item 13 on the cover page). Above 5.00 is the regulatory trigger threshold. Null only when the filing was malformed or the cover page omitted the field (rare; mostly pre-2010 archival filings).
- `filings[].sharesOwned` (number (nullable)): Aggregate shares beneficially owned across all positions in the filing. Includes shared voting + dispositive power. Always positive. Null only on malformed legacy filings. NOT split-adjusted — preserves the as-filed view.
- `filings[].priorPercent` (number (nullable)): Ownership percent from the prior filing by the same `(filer, issuer)` pair (auto-linked via amendment-chain detection — added v3.3.2). Null on the original filing (no prior). Useful for amendment-chain analysis without separate round-trips.
- `filings[].percentChange` (number (nullable)): Delta in `percentOfClass` vs the prior filing (current - prior). Positive = position increased; negative = position decreased. Null on the original filing. Useful for surfacing material amendments — e.g. amendments that move a 13G holder above the 10% activist trigger.
- `filings[].sharesChange` (number (nullable)): Delta in `sharesOwned` vs the prior filing (current - prior). Positive = additional accumulation; negative = position trim. Null on the original filing. Combine with `daysSincePriorFiling` to compute accumulation rate.
- `filings[].purpose` (string (nullable)): Classified filer intent — one of `passive`, `activist`, `m&a`, `going-private`, `proxy-fight`, `recapitalization`, `block-trade`, `unspecified`, etc. Derived from rule-based NLP classification of the filing's Item 4 (Purpose of Transaction). Null on legacy pre-classification filings. The single most-watched signal for activist-detection workflows.
- `meta` (object): Pagination + filter echo block: `{ total: integer, page: integer, size: integer, applied_filters: object }`. `total` is the cap-aware match count (full-corpus when below 10000).

**Since:** v3.0.0

**Utility:** The screening workhorse for Schedule 13D/13G beneficial-ownership filings — the SEC disclosure regime that requires anyone owning >5% of a public company's voting class to file within 10 days (13D) or annually (13G). Filter by issuer (ticker/CIK), filer (name/CIK), form type (`SC_13D` for active intent, `SC_13G` for passive), minimum ownership %, date range, amendment-only, and 13G→13D conversion-only. The right entry point for activist-investor surveillance ('every 13D filed against a healthcare name this quarter'), passive-fund tracking, and ownership-threshold crossings. Each row carries QoQ change deltas (`priorPercent`, `priorShares`, `percentChange`, `sharesChange`, `daysSincePriorFiling` — added v3.3.2) so amendment chains are first-class. Pair with `/ownership/beneficial-ownership/filings/{accession}` to drill into a single filing's structured payload.

**Use case:** Screen for activist positions, track ownership changes over time, find all 13D filings for a specific issuer, filter by purpose category.

**Parameters:**
- `issuerCik` (query, optional): Filter by issuer CIK (the company being reported on). Leading zeros stripped server-side — `0000320193`, `320193`, and `00320193` all match Apple. Combine with `formType` for issuer-specific scans (e.g. all `SC_13D`s filed against AAPL).
- `issuerTicker` (query, optional): Filter by issuer ticker (case-insensitive). Server normalizes to canonical hyphen form (`BRK.A` → `BRK-A`). Multi-class issuers preserve the share class actually filed.
- `filerCik` (query, optional): Filter by filer CIK (the entity DOING the reporting — typically a fund or family office). Leading zeros stripped. Use to track one filer's activity across all issuers.
- `filerName` (query, optional): Partial-match search on filer name (case-insensitive `ILIKE '%name%'`). Less precise than `filerCik` but useful when you don't yet know the CIK. Example: `filerName=ICAHN` finds all Carl-Icahn-affiliated filings (Icahn Enterprises LP, Icahn Partners, etc.).
- `formType` (query, optional): Form type filter — exactly one of `SC_13D` (active intent — 10-day filing window after crossing 5%), `SC_13D_A` (13D amendment), `SC_13G` (passive intent — annual), `SC_13G_A` (13G amendment). Note: SEC's published form names use slashes (`SC 13D/A`); FinRadar normalizes to underscores for URL safety.
- `minOwnership` (query, optional): Minimum aggregate `percent_of_class` threshold. Default behaviour returns ALL filings (including <5% amendments that filed for cessation of beneficial ownership). Set to `5.0` to filter to >5% positions only; set to `10.0` for the 'real material activist' subset; set to `0.01` to also surface near-zero amendments documenting position exits.
- `dateFrom` (query, optional): Inclusive lower bound on `filedAt` (acceptance date — not the trade date). Format ISO `YYYY-MM-DD`. Useful for incremental-pull workflows: query `dateFrom = last_run_timestamp` to catch only new filings.
- `dateTo` (query, optional): Inclusive upper bound on `filedAt`. Format ISO `YYYY-MM-DD`. Combine with `dateFrom` for closed ranges (e.g. one quarter).
- `isAmendment` (query, optional): When `true`, filter to amendment filings only (`SC_13D_A` + `SC_13G_A`). When `false`, filter to original filings only. Omit for both. Most-frequent amendments document position-size changes and ownership-purpose updates.
- `isConversion` (query, optional): When `true`, filter to 13G→13D conversions only — i.e. filings where a passive holder upgraded to active intent (often a leading indicator of activist campaigns or going-hostile-on-board signals). When `false`, exclude conversions. Omit for both. Conversions are a small minority of filings (<5%).
- `sort` (query, optional, default: filedAt): Sort field — one of `filedAt` (default; chronological), `aggregatePercent` (largest position first), `aggregateShares` (largest share count). Combine with `order=desc/asc`.
- `order` (query, optional, default: desc): Sort direction — `asc` (oldest/smallest first) or `desc` (newest/largest first; default).
- `page` (query, optional, default: 1): 1-based page number for pagination. `page=1` returns the first page; `page=2` returns the next, etc. Combined with `size` to compute offset (`offset = (page - 1) * size`).
- `size` (query, optional, default: 50): Page size, capped at 200 server-side. Larger pages reduce round-trips for bulk-export workflows but increase per-request latency. For full corpus enumeration use date-range chunking + `size=200`.

**Sample response:**
```json
{
  "filings": [
    {
      "accessionNumber": "0001193125-26-001234",
      "formType": "13D",
      "filedAt": "2026-04-15T20:14:32.000Z",
      "issuerCik": "0000320193",
      "issuerTicker": "AAPL",
      "nameOfIssuer": "APPLE INC",
      "filerCik": "0001067983",
      "filerName": "BERKSHIRE HATHAWAY INC",
      "percentOfClass": 5.84,
      "sharesOwned": 905560000,
      "priorPercent": 5.92,
      "percentChange": -0.08,
      "sharesChange": -10000000,
      "purpose": "passive"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```

### GET /api/v1/ownership/beneficial-ownership/filings/{accession}

Get full detail for a single beneficial ownership filing.

**Token cost:** 10 tokens per call

**Response fields:**
- `accessionNumber` (string): SEC accession echoed back in canonical dashed form regardless of input casing.
- `formType` (string): Schedule form type — one of `13D`, `13G`, `13D/A`, `13G/A`. The `/A` suffix preserved verbatim. 13D filings carry materially higher signal than 13G — they require disclosing INTENT, not just OWNERSHIP.
- `filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance. The 10-day filing-window deadline (for 13Ds) is computed from the trigger event date in the filing body, NOT from this `filedAt`.
- `issuer` (object): Issuer block: `{ cik: string (10-char zero-padded), ticker: string|null, name: string }`. The company being reported on. `ticker` may be null for private-issuer filings (M&A targets) or foreign-issuer filings without ADRs.
- `filers` (array): Array of all reporting persons on this filing — one entry per filer. Joint filings (Schedule 13D groups, family-office layered structures) have 2-9+ entries. Each entry: `{ cik, name, percentOfClass, sharesOwned, isOfficer, isDirector, signatureRole, address }`. Use `cik` as the stable join key against `/ownership/beneficial-ownership/filers/{cik}/portfolio`.
- `positions` (array): Array of position rows — typically one per filer (so length matches `filers[]`). Each entry exposes the SEC-mandated voting + dispositive-power decomposition: `{ filerCik, percentOfClass, sharesOwned, soleVotingPower, sharedVotingPower, soleDispositivePower, sharedDispositivePower, votingPower, dispositivePower }`. Critical for compliance — `sharedVotingPower` indicates a different control regime than `soleVotingPower`.
- `purpose` (object (nullable)): Classified purpose-of-transaction (Item 4) extracted via rule-based NLP. Shape: `{ primary: string, flags: { intends_to_acquire, opposes_management, seeks_board_seats, intends_proxy_fight, intends_tender_offer, intends_going_private, intends_recapitalization, ... } }`. `primary` enumerated as `passive`, `activist`, `m&a`, `going-private`, `proxy-fight`, `recapitalization`, `block-trade`, `unspecified`. Null on legacy pre-classification filings.
- `groupMembers` (array (nullable)): Array of co-filer entities when this filing is part of a Schedule 13D group (an explicit cooperation pact for accumulating > 5%). Each entry: `{ cik, name, isLeadFiler }`. Null when not a group filing (most are single-filer).
- `exhibits` (array (nullable)): Exhibits attached to the filing — array of `{ type, url, description }` (e.g. shareholder agreements, joint-filing agreements, settlement deeds, demand letters). Activist filings often have multi-page exhibits (Carl Icahn's letters to boards routinely run 5-10 pages). Null when filing has no exhibits.
- `footnotes` (array (nullable)): Per-filer footnotes parsed from the filing's notes section — array of `{ filerCik, footnote }`. Footnotes typically clarify the nature of indirect ownership (trust, LP, family office vehicle) or split-credit attribution. Null when filing has no footnotes.

**Since:** v3.0.0

**Utility:** Drill into the full structured payload of a single Schedule 13D/13G filing once you've identified the accession via `/ownership/beneficial-ownership/filings`. Returns the complete amendment-chain context: all filers (joint filings can have 2-9+ entities), per-filer position rows with separated voting/dispositive power, classified purpose with NLP-extracted intent flags (`intends_to_acquire`, `opposes_management`, `seeks_board_seats`, `intends_proxy_fight`), Schedule 13D group memberships, parsed exhibits with URLs, and per-filer footnotes. The right endpoint for activist-thesis research, M&A-related ownership disclosure analysis, and compliance / KYC due-diligence on filers.

**Use case:** Deep-dive into a specific 13D/13G filing to understand ownership structure, intent, and exhibits.

**Parameters:**
- `accession` (path, required): SEC accession number — accepts both canonical dashed form (`0001193125-22-104916`) and undashed form (`000119312522104916`). Server normalizes both. Returns 404 when the accession is not a 13D/13G/13D-A/13G-A filing in our parser cache (other form types return Form 4 / 13F detail via their respective endpoints).

**Sample response:**
```json
{
  "accessionNumber": "0001193125-26-001234",
  "formType": "13D",
  "filedAt": "2026-04-15T20:14:32.000Z",
  "issuer": {
    "cik": "0000320193",
    "ticker": "AAPL",
    "name": "APPLE INC"
  },
  "filers": [
    {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC",
      "percentOfClass": 5.84,
      "sharesOwned": 905560000
    }
  ],
  "positions": [
    {
      "filerCik": "0001067983",
      "percentOfClass": 5.84,
      "sharesOwned": 905560000,
      "votingPower": 905560000
    }
  ],
  "purpose": {
    "primary": "passive",
    "flags": {
      "intends_to_acquire": false,
      "opposes_management": false
    }
  }
}
```

### GET /api/v1/ownership/beneficial-ownership/issuers/{cik}/summary

Ownership summary for an issuer — all beneficial owners with latest positions.

**Token cost:** 10 tokens per call

**Response fields:**
- `issuerCik` (string): Issuer CIK echoed back in 10-char zero-padded form regardless of input.
- `issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when the issuer has no public-equity ticker (private-company M&A targets, foreign issuers without ADRs, dissolved entities).
- `nameOfIssuer` (string): Issuer name from the most recent filing's cover page (typically all-caps EDGAR convention). Multiple historical filings may have used variant names (rare; e.g. post-rebrand) — most-recent name wins.
- `asOf` (string): ISO-8601 UTC timestamp of the most-recent 13D/13G filing across all filers on this issuer. Use to gauge data freshness — values older than 12 months on a heavily-held name (where 13G's are mandatory annually) indicate either ingest staleness or a true ownership-stability period.
- `beneficialOwners` (array): Array of current beneficial owners — one row per `(filerCik, latest_filing)`. Sorted by `latestPercent DESC` (largest holder first). Excludes filers whose most-recent filing reported < 0.01% (cessation-of-ownership amendments). Empty array when the issuer has had filings but ALL have been cessations.
- `beneficialOwners[].filerCik` (string): Filer CIK in 10-char zero-padded form. The stable identifier — pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` for this filer's full beneficial-ownership book.
- `beneficialOwners[].filerName` (string): Filer name from the most recent filing (typically all-caps EDGAR convention). Casing preserved verbatim.
- `beneficialOwners[].latestPercent` (number (nullable)): Most recent reported `percent_of_class` for this filer. Above 5.00 by definition (filing trigger). Null only on legacy filings that omitted the field.
- `beneficialOwners[].latestShares` (number (nullable)): Most recent reported aggregate share count. Includes shared voting + dispositive power. NOT split-adjusted.
- `beneficialOwners[].latestFiledAt` (string): ISO-8601 UTC timestamp of the most recent filing by this filer. Useful for sorting by recency vs by size — a 5.5% holder who just filed is more actionable than a 25% holder whose last filing was 3 years ago.
- `beneficialOwners[].purpose` (string (nullable)): Classified intent from the most recent filing — `passive`, `activist`, `m&a`, `going-private`, `proxy-fight`, `recapitalization`, etc. Null on legacy pre-classification filings. The signal-density metric for the holder list.

**Since:** v3.0.0

**Utility:** Per-issuer roll-up of all 13D/13G beneficial owners — the >5%-of-class shareholder list as of the most recent filing per `(filer, issuer)` pair (amendments collapsed to the latest). Drives the 'Beneficial Owners' panel on every issuer-overview page. The right answer to 'who controls this company outside of mutual-fund passive ownership?' — surfacing activists (Carl Icahn at AAPL, Bill Ackman at QSR), strategic holders (Berkshire's preferred-stock-and-warrants in BAC), and 13G-passive concentrated holders (Vanguard, BlackRock, State Street). For per-FILER portfolio across multiple issuers use `/ownership/beneficial-ownership/filers/{cik}/portfolio`.

**Use case:** Build an ownership breakdown chart, identify top shareholders, detect activist positions.

**Parameters:**
- `cik` (path, required): Issuer CIK (the company being looked up — NOT the filer). Accepts both 10-char zero-padded form (`0000320193`) and unpadded (`320193`). Returns 404 when no 13D/13G filings have ever been filed against this issuer (e.g. very-thinly-held private companies or pre-IPO names).

**Sample response:**
```json
{
  "issuerCik": "0000320193",
  "issuerTicker": "AAPL",
  "nameOfIssuer": "APPLE INC",
  "asOf": "2026-05-01T20:55:12.000Z",
  "beneficialOwners": [
    {
      "filerCik": "0001067983",
      "filerName": "BERKSHIRE HATHAWAY INC",
      "latestPercent": 5.84,
      "latestShares": 905560000,
      "latestFiledAt": "2026-04-15T20:14:32.000Z",
      "purpose": "passive"
    }
  ]
}
```

### GET /api/v1/ownership/beneficial-ownership/filers/{cik}/portfolio

Portfolio view for a filer — all issuers they have beneficial ownership of.

**Token cost:** 10 tokens per call

**Response fields:**
- `filerCik` (string): Filer CIK echoed back in 10-char zero-padded form regardless of input.
- `filerName` (string): Filer name from the most recent filing (typically all-caps EDGAR convention). For activists this often surfaces multi-entity structures — the most-recently-filed legal name wins.
- `positions` (array): Array of current beneficial-ownership positions — one row per issuer where this filer has a non-cessation 13D/13G position. Sorted by `latestPercent DESC` (largest position first). Excludes issuers whose most-recent filing was a cessation amendment (< 0.01%).
- `positions[].issuerCik` (string): Issuer CIK in 10-char zero-padded form. Stable join key for issuer-side queries.
- `positions[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when issuer has no public-equity ticker (private companies, foreign issuers without ADRs).
- `positions[].nameOfIssuer` (string): Issuer name from the most recent filing's cover page (typically all-caps EDGAR convention).
- `positions[].latestPercent` (number (nullable)): Latest reported `percent_of_class` for this filer at this issuer. Above 5.00 by definition (filing trigger). Null on legacy filings that omitted the field.
- `positions[].latestShares` (number (nullable)): Latest reported aggregate share count. Includes shared voting + dispositive power. NOT split-adjusted.
- `positions[].latestFiledAt` (string): ISO-8601 UTC timestamp of the most recent filing. Use to detect stale positions — values older than 12 months on a 13G holder may indicate ingest staleness or an annual-filing window not yet reached.
- `positions[].purpose` (string (nullable)): Classified intent at the latest filing — `passive`, `activist`, `m&a`, `going-private`, `proxy-fight`, `recapitalization`, etc. Null on legacy pre-classification filings. Look for `passive` → `activist` purpose transitions across time as the strongest activist-conversion signal.
- `meta` (object): Pagination + filter echo block: `{ total: integer, limit: integer }`. `total` is the full position count; pagination not currently exposed via this endpoint (positions list is bounded since most filers hold < 100 positions).

**Since:** v3.0.0

**Utility:** Per-filer beneficial-ownership portfolio: every issuer where this filer has filed a 13D/13G with a current >5% (or >0.01% non-cessation) position. The inverse of `/issuers/{cik}/summary` — drill into one specific activist or fund (Carl Icahn, Bill Ackman, Berkshire Hathaway, Engine No. 1) and get the full list of companies they hold significant beneficial ownership in. Drives activist-portfolio tracker dashboards, copycat-investor research, and 'who else does Carl Icahn target?' workflows. Pair with `/ownership/holders/{uuid}/filing-history` for the time-ordered filing chain across both 13D/G and 13F sources.

**Use case:** Track an activist investor's portfolio of positions across multiple companies.

**Parameters:**
- `cik` (path, required): Filer CIK (the entity DOING the reporting — fund, family office, individual). Accepts both 10-char zero-padded form (`0001067983`) and unpadded (`1067983`). Common activist CIKs: `0001412082` (Carl Icahn), `0001336528` (Pershing Square — Bill Ackman), `0001067983` (Berkshire Hathaway). Returns 404 when the CIK has never filed a 13D/13G.

**Sample response:**
```json
{
  "filerCik": "0001067983",
  "filerName": "BERKSHIRE HATHAWAY INC",
  "positions": [
    {
      "issuerCik": "0000320193",
      "issuerTicker": "AAPL",
      "nameOfIssuer": "APPLE INC",
      "latestPercent": 5.84,
      "latestShares": 905560000,
      "latestFiledAt": "2026-04-15T20:14:32.000Z",
      "purpose": "passive"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```

### GET /api/v1/ownership/beneficial-ownership/activists

Activist tracker — recent 13D filings with NLP purpose classification.

**Token cost:** 10 tokens per call

**Response fields:**
- `activists` (array): Array of activist-classified filing rows, sorted by `filedAt DESC` (most recent first). Empty array when no filings match the filters in the date window. Pre-filtered upstream — every row has `purpose='activist'` (or one of the activist-aligned purpose categories).
- `activists[].accessionNumber` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `/ownership/beneficial-ownership/filings/{accession}` for full filing detail (all filers, exhibits, footnotes).
- `activists[].filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance. Compare against issuer's stock-price action — activist 13D filings often trigger 5-15% next-day price moves.
- `activists[].issuerCik` (string): Issuer CIK in 10-char zero-padded form. The company being targeted by the activist campaign.
- `activists[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null for private-company targets (M&A activist filings on pending deals occasionally surface against unlisted entities).
- `activists[].filerCik` (string): Filer CIK in 10-char zero-padded form (the activist entity). Pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` for the activist's full position book.
- `activists[].filerName` (string): Activist filer name (typically all-caps EDGAR convention). Common high-signal names: `ICAHN CARL C`, `PERSHING SQUARE CAPITAL MANAGEMENT LP`, `TRIAN FUND MANAGEMENT LP`, `ELLIOTT ASSOCIATES LP`, `STARBOARD VALUE LP`, `ENGINE NO 1 LP`.
- `activists[].percentOfClass` (number (nullable)): Reported aggregate `percent_of_class`. Above 5.00 by definition (filing trigger). Activist positions typically fall in 5-12% range — much higher than that and the filer crosses additional regulatory thresholds (e.g. 10% for short-swing profit rules).
- `activists[].purpose` (string): Always one of the activist-aligned purpose categories (the endpoint pre-filters out `passive`). Values: `activist`, `m&a`, `proxy-fight`, `going-private`, `recapitalization`, `restructuring`. Use the more granular `purposeCategory` filter to drill further.
- `activists[].intentFlags` (object (nullable)): Granular boolean flags from rule-based NLP extraction of Item 4 text. Schema: `{ opposes_management: bool, board_seat_demand: bool, m&a_pressure: bool, intends_proxy_fight: bool, intends_tender_offer: bool, ... }`. The signal-density layer ABOVE the single `purpose` field — a `purpose='activist'` filing with `board_seat_demand=true AND opposes_management=true` is a near-certain proxy fight.
- `meta` (object): Pagination + filter echo block: `{ total: integer, page: integer, size: integer, applied_filters: object }`. `total` is full-corpus match count for the filter set.

**Since:** v3.0.0

**Utility:** The activist-investor watchlist endpoint — pre-filtered to filings classified as `activist` intent by FinRadar's rule-based NLP purpose classifier (running across the Item 4 'Purpose of Transaction' text on every 13D). Drives the canonical 'who's launching activist campaigns this week?' dashboard. Filterable by issuer ticker, filer name (e.g. all Trian Fund Management filings), minimum ownership %, date range, and 13-category purpose taxonomy (BOARD_REPRESENTATION, PROXY_CONTEST, MERGER_ACQUISITION, TENDER_OFFER, etc.). Each row carries `intentFlags` — granular boolean signals (`opposes_management`, `board_seat_demand`, `m&a_pressure`) that go beyond the single `purpose` category. The right entry point for hostile-takeover surveillance, proxy-fight tracking, and copycat-investor research. For all-purposes (passive + activist) ownership data use `/ownership/beneficial-ownership/filings`.

**Use case:** Monitor activist campaigns, screen for board fights, merger pressure, restructuring demands. Filter by ticker, filer name, or minimum ownership.

**Parameters:**
- `issuerTicker` (query, optional): Issuer ticker filter, case-insensitive (server normalizes to canonical hyphen form). Returns only activist filings against this specific issuer. Useful for company-overview pages: 'is anyone running an activist campaign against this name right now?'
- `filerName` (query, optional): Partial-match search on filer name (case-insensitive `ILIKE '%name%'`). Useful for tracking known activists across all their targets — `filerName=ICAHN` finds all Carl-Icahn-affiliated filings, `filerName=PERSHING` finds all Bill-Ackman-affiliated filings. Less precise than `filerCik`-based portfolio queries; use this for exploration.
- `minOwnership` (query, optional): Minimum aggregate `percent_of_class` threshold (added v3.7.3). Default returns all activist filings; setting `5.0` surfaces material >5% activist positions; setting `10.0` returns only large-block activists. Useful for filtering out de minimis filings that don't carry real campaign weight.
- `dateFrom` (query, optional): Inclusive lower bound on `filedAt`. Format ISO `YYYY-MM-DD`. For incremental polling, set to `last_run_timestamp` to pick up only newly-filed activist campaigns.
- `dateTo` (query, optional): Inclusive upper bound on `filedAt`. Format ISO `YYYY-MM-DD`. Combine with `dateFrom` for closed ranges.
- `purposeCategory` (query, optional): Filter to one of 13 purpose categories: `PASSIVE_INVESTMENT`, `ACTIVE_INVESTMENT`, `BOARD_REPRESENTATION` (board-seat demands), `MERGER_ACQUISITION` (M&A intent), `TENDER_OFFER`, `PROXY_CONTEST` (proxy fights), `CHANGE_MANAGEMENT` (CEO-replacement campaigns), `RESTRUCTURING`, `CAPITAL_RETURN` (buyback/dividend pressure), `GOVERNANCE_CHANGE`, `STRATEGIC_ALTERNATIVES` (sale-of-company demand), `SPIN_OFF`, `OTHER`. Each filing maps to exactly one primary category.
- `page` (query, optional, default: 1): 1-based page number. `page=1` returns the first page (most-recent activist filings); increment to walk back chronologically.
- `size` (query, optional, default: 50): Page size, capped at 200 server-side. Activist filings are a small minority of 13D/13G corpus (~5-10%) so even broad date ranges stay below the deep-pagination cap.

**Sample response:**
```json
{
  "activists": [
    {
      "accessionNumber": "0001193125-26-001999",
      "filedAt": "2026-04-15T20:14:32.000Z",
      "issuerCik": "0000051143",
      "issuerTicker": "IBM",
      "filerCik": "0001637207",
      "filerName": "TRIAN FUND MANAGEMENT LP",
      "percentOfClass": 6.2,
      "purpose": "activist",
      "intentFlags": {
        "opposes_management": true,
        "board_seat_demand": true
      }
    }
  ]
}
```

### GET /api/v1/ownership/beneficial-ownership/conversions

List 13G-to-13D and 13D-to-13G filing type conversions.

**Token cost:** 10 tokens per call

**Response fields:**
- `conversions` (array): Array of conversion rows, sorted by `convertedAt DESC` (most recent first). Each row pairs the prior + current filings so the conversion direction and the gap-since-prior are observable in one go. Empty array when no conversions in the date window.
- `conversions[].filerCik` (string): Filer CIK in 10-char zero-padded form (the entity that converted). Pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` to see the filer's full position book.
- `conversions[].filerName` (string): Filer name from the current filing (typically all-caps EDGAR convention). For activist conversions, common high-signal names: `TRIAN FUND MANAGEMENT LP`, `STARBOARD VALUE LP`, `ELLIOTT INVESTMENT MANAGEMENT LP`.
- `conversions[].issuerCik` (string): Issuer CIK in 10-char zero-padded form (the company being targeted). Pass to `/ownership/beneficial-ownership/issuers/{cik}/summary` for the full beneficial-owner roll-up.
- `conversions[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null only for private-issuer conversions (rare; most M&A target conversions resolve).
- `conversions[].priorFormType` (string): Form type of the PRIOR filing — `13G` (passive) or `13D` (active). Together with `currentFormType` defines the conversion direction.
- `conversions[].currentFormType` (string): Form type of the CURRENT filing that triggered the conversion. The interesting cases: `priorFormType=13G AND currentFormType=13D` (passive going active — typical activist campaign launch), `priorFormType=13D AND currentFormType=13G` (active winding down).
- `conversions[].direction` (string): Conversion direction — literal `"passive_to_active"` (13G→13D, activist campaign launching) or `"active_to_passive"` (13D→13G, campaign winding down). The single most important field on this endpoint — filter on `direction` for direction-specific surveillance.
- `conversions[].priorAccession` (string): SEC accession of the PRIOR filing. Pass to `/ownership/beneficial-ownership/filings/{accession}` to retrieve the prior filing's full structured payload (purpose, intent flags, exhibits).
- `conversions[].currentAccession` (string): SEC accession of the CURRENT (conversion-triggering) filing. Pass to `/ownership/beneficial-ownership/filings/{accession}` for the new filing's full payload — typically more interesting than the prior filing since it carries the new declared intent.
- `conversions[].convertedAt` (string): ISO-8601 UTC timestamp of the CURRENT filing (the moment the conversion was disclosed). The `convertedAt - priorFiledAt` gap is itself a signal — fast conversions (within weeks) suggest a planned escalation; slow conversions (months) suggest opportunistic shifts.

**Since:** v3.0.0

**Utility:** Surfaces filings where a beneficial owner CONVERTED between 13G (passive) and 13D (active) reporting status — a rare but extremely high-signal event because the conversion is the regulatory moment a filer's PUBLICLY-DECLARED INTENT changed. The 13G→13D direction (`passive_to_active`) is the canonical 'activist campaign launching' indicator: a fund that was reporting passively suddenly switches to active disclosure because they intend to influence management. The reverse direction (`active_to_passive`) often signals the campaign winding down — settlement reached, board seats won, position taking back to passive holding. Each row pairs the prior + current accession so the conversion is observable in one round-trip. The most actionable single endpoint in the 13D/G surface for proxy-fight surveillance.

**Use case:** Early detection of passive holders turning activist, or activist campaigns winding down.

**Parameters:**
- `dateFrom` (query, optional): Inclusive lower bound on `convertedAt` (the date of the conversion-triggering current filing). Format ISO `YYYY-MM-DD`. Use to incrementally poll only new conversions: `dateFrom = last_run_timestamp`.
- `page` (query, optional, default: 1): 1-based page number. Conversions are a small minority of 13D/G corpus (<2%); even broad date ranges typically fit on a single page.
- `size` (query, optional, default: 50): Page size, capped at 200 server-side. Practical cap matters less here than on the broader filings endpoint because the conversion universe is small.

**Sample response:**
```json
{
  "conversions": [
    {
      "filerCik": "0001637207",
      "filerName": "TRIAN FUND MANAGEMENT LP",
      "issuerCik": "0000051143",
      "issuerTicker": "IBM",
      "priorFormType": "13G",
      "currentFormType": "13D",
      "direction": "passive_to_active",
      "priorAccession": "0001193125-25-987654",
      "currentAccession": "0001193125-26-001999",
      "convertedAt": "2026-04-15T20:14:32.000Z"
    }
  ]
}
```

### GET /api/v1/ownership/beneficial-ownership/groups

List group filings where multiple parties act together.

**Token cost:** 10 tokens per call

**Response fields:**
- `groups` (array): Array of group rows, sorted by `aggregatePercent DESC` (largest groups first). Each group represents one coordinated filing structure against one issuer. A single issuer can have multiple groups (overlapping or distinct membership) if different consortia have filed separate Schedule 13Ds. Empty array on no match.
- `groups[].groupId` (string): Internal stable group identifier in `grp_XXXXXX` format (e.g. `grp_8a1f`). Unique per `(issuer, group_member_set)` tuple — re-runs return the same ID. Use as a join key when caching group state across polls.
- `groups[].issuerCik` (string): Target issuer CIK in 10-char zero-padded form. The company the coordinated group is filing against.
- `groups[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null for private-company target groups (rare; most groups target public issuers).
- `groups[].members` (array): Array of member filer rows. Length 2-9+ (2 is most common — typical PE LP+GP structure; 5+ is rare and usually indicates a multi-party activist coalition like Engine No. 1's 2021 ExxonMobil board fight). Sorted by member CIK for stable ordering.
- `groups[].members[].filerCik` (string): Member filer CIK in 10-char zero-padded form. Each member is itself a 13D/G filer — pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` to see their full beneficial-ownership book outside of this group.
- `groups[].members[].filerName` (string): Member filer name as filed (typically all-caps EDGAR convention). For activist groups commonly mixes fund-entity names + individual principal names (e.g. `TRIAN FUND MANAGEMENT LP` + `NELSON PELTZ`).
- `groups[].aggregatePercent` (number): Group's combined aggregate `percent_of_class` summed across all members. Above 5.00 by definition (since group membership triggers a Schedule 13D). Wolf-pack groups typically aggregate to 6-12%; SPAC sponsor consortia often 15-25%.
- `groups[].aggregateShares` (number): Group's combined aggregate share count summed across all members. NOT split-adjusted — preserves as-filed view. Use this with `aggregatePercent` to compute the implied total class outstanding.
- `groups[].latestFiledAt` (string): ISO-8601 UTC timestamp of the most recent group-member filing. With `activeOnly=true`, this will always be within the last 12 months. Use to detect group-state changes — long gaps may indicate unfiled cessations or membership changes that haven't yet hit our parser.

**Since:** v3.0.0

**Utility:** Schedule 13D groups — coordinated filers who file together as a single beneficial-ownership group under SEC Section 13(d)(3) (a 'group' is formed whenever 2+ entities agree to act together for the purpose of acquiring or holding the issuer's securities). Each row lists ALL members + their aggregate position. The most actionable use case is detecting 'wolf pack' formations — 2-5 activist funds quietly coordinating a >5% position before any individual filer crosses the threshold. Also surfaces SPAC sponsor consortia, family-office layered structures, and buyout-fund + management rollups in pre-merger filings. Pair with `/ownership/beneficial-ownership/activists` to see groups whose purpose is classified as activist intent.

**Use case:** Identify coordinated investor groups, wolf pack formations.

**Parameters:**
- `issuerCik` (query, optional): Filter to groups targeting this issuer (the company being collectively held). Accepts both 10-char zero-padded form (`0000051143`) and unpadded (`51143`). Returns empty array when no groups have ever filed against this issuer (most companies).
- `activeOnly` (query, optional, default: true): When `true` (default), returns only groups whose latest filing was within the last 12 months — i.e. structurally still active. When `false`, includes historical groups whose campaigns have wound down (member departure, group dissolution amendment, full position exit). Set to `false` for activism-history research; leave default for current-state surveillance.

**Sample response:**
```json
{
  "groups": [
    {
      "groupId": "grp_8a1f",
      "issuerCik": "0000051143",
      "issuerTicker": "IBM",
      "members": [
        {
          "filerCik": "0001637207",
          "filerName": "TRIAN FUND MANAGEMENT LP"
        },
        {
          "filerCik": "0001637208",
          "filerName": "NELSON PELTZ"
        }
      ],
      "aggregatePercent": 6.2,
      "aggregateShares": 56830000,
      "latestFiledAt": "2026-04-15T20:14:32.000Z"
    }
  ]
}
```