/api/v1/ownership/holdersSearch unified holders across all filing types.
Search unified holders across all filing types.
5 tokensSince v3.0.0
Why use this
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.
Common 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`.
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. Each row carries is_insider / is_institutional / is_beneficial_owner flags so consumers can answer cross-regime questions in a single call (e.g. 'is this entity both a 13F filer AND a 13D filer?'). The holder_uuid is the stable identifier across all three SEC reporting regimes — generated by deterministic (canonical_cik, normalized_name) clustering, stable across linker re-runs. Pass it to GET /api/v1/ownership/holders/{uuid} for full detail (alternate CIKs, derived metadata) or GET /api/v1/ownership/cross-reference/{holder_uuid} for cross-source filing-history feeds. For position-state-by-issuer drill-downs use the /positions/... endpoints in this same group.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| 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). | berkshire |
| 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. | 0001067983 |
| 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. | institutional |
| page | query | optional | 1 | — | 1-indexed page number for pagination. | — |
| size | query | optional | 50 | — | Page size (max 200). Values > 200 silently clamp to 200. | — |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| holders | array | no | 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 | no | 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 | no | 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 | yes | 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 | no | 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 | no | `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 | no | `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 | no | `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 | no | Total filing count across ALL three regimes for this holder. Useful for sorting holders by activity volume client-side. |
| meta | object | no | Pagination block: `{ total: integer, page: integer, size: integer, pages: integer }`. `total` is the full match count across all pages. |
Sample response
·
- "holders":
- "meta":
- "total": 2
- "page": 1
- "size": 50
- "pages": 1
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/api/v1/ownership/holders?api_Token=YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).