/api/v1/ownership/holders/{uuid}/filing-historyAll filings across Form 4, 13F, and 13D/G for a unified holder.
All filings across Form 4, 13F, and 13D/G for a unified holder.
10 tokensSince v3.1.0
Why use this
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.
Common use case
See the complete SEC filing history of a person/fund in chronological order.
Returns the full filing history for a unified holder (a holder identity linked across Form 4, 13F, and 13D/G via CIK + name matching). Use the holder UUID returned by the unified-holders search to retrieve the chronological filing trail across all form types — gives a single audit view of one beneficial-owner identity.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| 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. | 7f1a2b30-c4d5-46e7-9f01-23456789abcd |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| holder | object | no | 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 | no | 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 | no | 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 | no | 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 | no | 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 | yes | 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 | yes | 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 | yes | 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 | no | Pagination + filter echo block: `{ total: integer, limit: integer }`. `total` is the full filing count for the holder across all form types. |
Sample response
·
- "holder":
- "uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd"
- "name": "BERKSHIRE HATHAWAY INC"
- "cik": "0001067983"
- "type": "institution"
- "history":
- "meta":
- "total": 1
- "limit": 100
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/{uuid}/filing-history?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).