# Unified Holders — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 33200190
> Fetch this file at: https://uat.finradarapi.com/llms/unified-holders.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.

---

## Unified Holders

Cross-system holder identity linking Form 4 insiders, 13F institutional managers, and 13D/G beneficial owners into unified profiles.

### GET /api/v1/ownership/holders

Search unified holders across all filing types.

**Token cost:** 5 tokens per call

**Response fields:**
- `holders` (array): Array of unified-holder rows matching the search. Order: by relevance score DESC for `q` search, by name ASC for `cik` exact match. Empty array on no matches — does NOT 404.
- `holders[].holder_uuid` (string): Stable UUID identifier across all three SEC reporting regimes (Form 4 / 13F / 13D-G). Generated by the Phase 47 holder-linker via deterministic hashing of `(canonical_cik, normalized_name)` clustering. Pass to [GET /api/v1/ownership/holders/{uuid}](/docs/ownership-and-positions/unified-holders/get-ownership-holders-uuid) for full detail or [GET /api/v1/ownership/cross-reference/{holder_uuid}](/docs/ownership-and-positions/unified-holders/get-ownership-cross-reference) for cross-source filing history.
- `holders[].name` (string): Canonical holder name (typically all-caps EDGAR convention for SEC-registered entities). For natural persons this preserves the as-filed Form 4 name (`BUFFETT WARREN E`); for institutions it's the legal entity name.
- `holders[].cik` (string (nullable)): Primary 10-character zero-padded SEC CIK. Multi-CIK holders (rare — typically post-merger institutions) expose a primary CIK here and the full list under [GET /api/v1/ownership/holders/{uuid}](/docs/ownership-and-positions/unified-holders/get-ownership-holders-uuid) `alternate_ciks[]`. Null on holders identified by name-only (no SEC CIK ever assigned — rare; mostly natural-person consortium members in 13D groups).
- `holders[].type` (string): Primary classification — `individual` (natural persons — Buffett, Icahn, Ackman), `institution` (fund entities — Berkshire, BlackRock, Vanguard), `group` (Schedule 13D consortia — multi-party activist groups). Derived from filing patterns + name heuristics by the Phase 47 linker.
- `holders[].is_insider` (boolean): `true` when the holder has filed at least one Form 3/4/5 (Section 16 insider). Section 16 covers officers, directors, and 10%+ beneficial owners.
- `holders[].is_institutional` (boolean): `true` when the holder has filed at least one 13F-HR/NT (institutional investment manager — required for entities with $100M+ AUM in 13(f) securities).
- `holders[].is_beneficial_owner` (boolean): `true` when the holder has filed at least one Schedule 13D / 13G / 13D-A / 13G-A (beneficial ownership of >5% of any registered class).
- `holders[].filing_count` (integer): Total filing count across ALL three regimes for this holder. Useful for sorting holders by activity volume client-side.
- `meta` (object): Pagination block: `{ total: integer, page: integer, size: integer, pages: integer }`. `total` is the full match count across all pages.

**Since:** v3.0.0

**Utility:** Search the Phase 47 unified-holder layer — the cross-system identity table that links Form 4 insiders, 13F institutional managers, and 13D/G beneficial owners into one canonical profile per holder. The natural search entrypoint for 'who is this entity, and what kinds of filings have they made?'. Each row carries cross-system flags (`is_insider`, `is_institutional`, `is_beneficial_owner`) so a customer can answer 'is Berkshire Hathaway both a 13F filer AND a 13D filer?' (yes — for AAPL pre-2020) in one call. The `holder_uuid` is the stable identifier across all three SEC reporting regimes — pass it to the per-holder detail endpoints for drill-downs.

**Use case:** Building a unified holder-profile UI where users can search for any party (e.g. `Buffett` or `Berkshire` or `0001067983`) and see every filing-type that party has been involved in. Also useful for 'find all hedge funds with both insider activity AND 13F holdings' screens — filter `type=insider` AND post-filter on `is_institutional=true`.

**Parameters:**
- `q` (query, optional): Name search (partial, case-insensitive). Trigram fuzzy matching on the holder_name field — `berkshire` matches `BERKSHIRE HATHAWAY INC`, `BERKSHIRE GROUP LP`, etc. Either `q` or `cik` must be provided (server returns 400 when both are omitted).
- `cik` (query, optional): CIK exact match. Both 10-character zero-padded (`0001067983`) and short unpadded (`1067983`) formats accepted via server-side `ltrim('0')` normalization. Either `q` or `cik` must be provided.
- `type` (query, optional): Filter holders by primary type: `insider` (Form 4 / Section 16 filers), `institutional` (13F filers), `beneficial` (13D/13G filers). Omit for all types. Multi-type holders (e.g. Berkshire — both institutional AND beneficial) appear under their primary type but expose all flags.
- `page` (query, optional, default: 1): 1-indexed page number for pagination.
- `size` (query, optional, default: 50): Page size (max 200). Values > 200 silently clamp to 200.

**Sample response:**
```json
{
  "holders": [
    {
      "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
      "name": "BERKSHIRE HATHAWAY INC",
      "cik": "0001067983",
      "type": "institution",
      "is_insider": false,
      "is_institutional": true,
      "is_beneficial_owner": true,
      "filing_count": 487
    },
    {
      "holder_uuid": "a2c4e6f8-1b3d-5e7f-9a0b-c1d2e3f4a5b6",
      "name": "BUFFETT WARREN E",
      "cik": "0000315090",
      "type": "individual",
      "is_insider": true,
      "is_institutional": false,
      "is_beneficial_owner": true,
      "filing_count": 124
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "size": 50,
    "pages": 1
  }
}
```

### GET /api/v1/ownership/holders/{uuid}

Get holder detail with alternate CIKs and cross-system flags.

**Token cost:** 5 tokens per call

**Response fields:**
- `holder_uuid` (string): Echoed UUID identifier.
- `name` (string): Canonical holder name.
- `type` (string): Primary classification — `individual` / `institution` / `group`.
- `primary_cik` (string (nullable)): Primary 10-character zero-padded SEC CIK (the canonical CIK chosen by the linker; typically the most-filed CIK across all regimes). Null on holders identified by name-only.
- `alternate_ciks` (array): Array of alternate 10-char zero-padded CIKs the same holder has used across filings. Multi-CIK holders are uncommon (post-merger institutions, holding-company-vs-subsidiary distinctions, or 13F-filer-vs-Section-16-filer CIK splits). Empty array for the typical single-CIK holder.
- `name_aliases` (array): Array of historical name variants the holder has filed under (former names, DBAs, post-rebrand identifiers). E.g. Facebook -> Meta Platforms appears here as `["FACEBOOK INC", "META PLATFORMS INC"]`. Useful for surfacing 'formerly known as' on profile pages.
- `is_insider` (boolean): `true` when the holder has filed Form 3/4/5.
- `is_institutional` (boolean): `true` when the holder has filed 13F-HR/NT.
- `is_beneficial_owner` (boolean): `true` when the holder has filed Schedule 13D/G.
- `filing_counts` (object): Per-regime filing counts: `{ form_4: integer, form_13f: integer, form_13dg: integer }`. Useful for activity-level visualization on profile pages (e.g. donut chart of filing-type distribution).
- `first_filing_at` (string (nullable)): ISO-8601 UTC timestamp of the holder's earliest known filing across all three regimes. Null on rare holders with empty filing history.
- `last_filing_at` (string (nullable)): ISO-8601 UTC timestamp of the holder's most-recent filing. Useful for sorting profile pages by recency or surfacing 'last seen' on dashboards.

**Since:** v3.0.0

**Utility:** Full profile of a unified holder by UUID — includes alternate CIKs (multi-CIK holders post-merger), name aliases (former names + DBAs), cross-system filing-volume metadata (per-regime counts + first/last filing dates), and the same `is_insider/is_institutional/is_beneficial_owner` flags surfaced by the search endpoint. The natural detail-page backend after a [GET /api/v1/ownership/holders](/docs/ownership-and-positions/unified-holders/get-ownership-holders) search palette resolves a UUID. Pair with [GET /api/v1/ownership/holders/{uuid}/filing-history](/docs/ownership-and-positions/unified-holders/get-ownership-holders-uuid-filing-history) for the filing timeline view.

**Use case:** Building a comprehensive holder-profile page (e.g. `/holders/{uuid}`) with all CIKs, name aliases, filing-volume metadata, and cross-system flags. Also useful for verifying that the Phase 47 linker has correctly clustered identities — if an expected alternate CIK is missing from `alternate_ciks[]`, the linker may need a manual override (rare; <0.5% of holders).

**Parameters:**
- `uuid` (path, required): Holder UUID — the stable Phase-47 identifier. Look up via [GET /api/v1/ownership/holders](/docs/ownership-and-positions/unified-holders/get-ownership-holders) (`q` or `cik` search). UUIDs are deterministic across linker re-runs for the same `(canonical_cik, normalized_name)` cluster, so they're safe to persist client-side. Returns 404 on unknown UUIDs.

**Sample response:**
```json
{
  "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "name": "BERKSHIRE HATHAWAY INC",
  "type": "institution",
  "primary_cik": "0001067983",
  "alternate_ciks": [],
  "name_aliases": [
    "BERKSHIRE HATHAWAY INC"
  ],
  "is_insider": false,
  "is_institutional": true,
  "is_beneficial_owner": true,
  "filing_counts": {
    "form_4": 0,
    "form_13f": 102,
    "form_13dg": 8
  },
  "first_filing_at": "1999-11-15T17:00:00Z",
  "last_filing_at": "2026-04-15T20:14:32Z"
}
```

### GET /api/v1/ownership/holders/{uuid}/filing-history

All filings across Form 4, 13F, and 13D/G for a unified holder.

**Token cost:** 10 tokens per call

**Response fields:**
- `holder` (object): Holder identity block: `{ uuid: string, name: string, cik: string, type: 'individual'|'institution'|'group' }`. The unified profile across all three SEC reporting regimes. `type` is derived: `individual` for natural persons (Warren Buffett, Carl Icahn), `institution` for fund entities, `group` for Schedule 13D consortia.
- `history` (array): Array of filing-history rows, sorted by `filedAt DESC` (most recent first). Mixes Form 4, 13F-HR, 13D, 13G, and amendment variants — one row per filing this holder has been a party to. Empty array on holders with no SEC filing footprint (rare; the linker only creates UUIDs for holders observed in at least one filing).
- `history[].formType` (string): Canonical form type — `4` (Form 4 insider), `13F-HR` (13F holdings), `13D` (active beneficial ownership), `13G` (passive), `13D/A` / `13G/A` (amendments), `3` (initial Form 3), `5` (annual Form 5). Use to filter client-side to one regime when needed.
- `history[].accessionNumber` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to the form-type-specific filing-detail endpoint (`/insider-module/api/insiders/filings/{accession_number}` for Form 4, `/ownership/beneficial-ownership/filings/{accession}` for 13D/G).
- `history[].filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance. The chronological-order key for the timeline. For Form 4 this is typically within 2 business days of the trade; for 13F it's within 45 days of the quarter end; for 13D it's within 10 days of the trigger event.
- `history[].issuerCik` (string (nullable)): Issuer CIK when the filing has a single issuer (Form 4, 13D, 13G all do). Null for 13F-HR filings (those are portfolio-level — the issuer field is per-position not per-filing). Use the per-position drill-down for 13F detail.
- `history[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when (a) the filing is a 13F-HR (multi-issuer), or (b) the issuer has no public-equity ticker.
- `history[].action` (string (nullable)): Human-readable action summary derived from the filing's structured data — e.g. `"Purchased 5,000 shares at $175.25"` (Form 4), `"13G filed at 5.2% of class"` (13G), `"13D/A: position increased to 7.1%"` (13D amendment), `"13F-HR: 245 positions, $42.3B AUM"` (13F). Useful for one-line timeline rendering. Null on legacy filings where structured data is incomplete.
- `meta` (object): Pagination + filter echo block: `{ total: integer, limit: integer }`. `total` is the full filing count for the holder across all form types.

**Since:** v3.1.0

**Utility:** Cross-system filing timeline for a single beneficial-owner identity — unifies Form 4 insider transactions, 13F institutional positions, and 13D/G beneficial-ownership filings into one chronological feed. The Phase 31 Unified Holders linker matches identities across these three SEC reporting regimes via CIK + name fuzzy matching, so a single fund (e.g. Berkshire Hathaway) shows you both its Form 4 insider filings (Warren Buffett's personal trades), its 13F holdings (the institutional book), AND its 13D/G beneficial ownership (large-block positions like AAPL pre-2020). The single audit view that answers 'show me everything this entity has filed with the SEC, in time order'. Pair with `/ownership/positions/{holder_uuid}/issuer/{issuer_cik}` for the position-state view of the same data, or `/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history` for time-series of one position.

**Use case:** See the complete SEC filing history of a person/fund in chronological order.

**Parameters:**
- `uuid` (path, required): Unified holder UUID — internally generated by the Phase 31 holder-linker, NOT a SEC-issued identifier. Lookup the UUID by CIK or name via `GET /api/v1/ownership/holders` (which has a `q` search parameter). UUIDs are stable across re-runs of the linker for the same `(cik, name)` cluster.

**Sample response:**
```json
{
  "holder": {
    "uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
    "name": "BERKSHIRE HATHAWAY INC",
    "cik": "0001067983",
    "type": "institution"
  },
  "history": [
    {
      "formType": "13D",
      "accessionNumber": "0001193125-26-001234",
      "filedAt": "2026-04-15T20:14:32.000Z",
      "issuerCik": "0000320193",
      "issuerTicker": "AAPL",
      "action": "Filed 13D at 5.84%"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```