/api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}Calculate current ownership position for a holder in an issuer.
Calculate current ownership position for a holder in an issuer.
10 tokensSince v3.1.0
Why use this
Compute the current (or as-of-date) ownership position of a unified holder in an issuer by REPLAYING THE EVENT-SOURCED LEDGER: take the most recent 13D/13G or 13F assertion as the base position, then apply Form 4 transaction deltas chronologically forward to today. Solves the per-holder-per-issuer 'what's their current position?' question without forcing the customer to manually replay 30+ filings. Returns the source form types contributing to the calculation so you can audit the derivation. Pair with `/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history` for the time-series version of the same calculation. The right endpoint when you need a single-number answer like 'how many AAPL shares does Berkshire hold right now?'
Common use case
Get point-in-time ownership estimate with confidence scoring.
Current position for a (holder, issuer) pair — derived from the unified-holder ledger that combines Form 4 transactions, 13F holdings, and 13D/G beneficial-ownership disclosures. Returns one canonical position row representing the holder's economic exposure to the issuer right now. Use GET /api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history for the full event timeline.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| holder_uuid | path | required | — | — | Unified holder UUID — internally generated by the Phase 31 holder-linker. Lookup via `GET /api/v1/ownership/holders` with the `q` search parameter. UUIDs are stable across re-runs for the same `(cik, name)` cluster. | 7f1a2b30-c4d5-46e7-9f01-23456789abcd |
| issuer_cik | path | required | — | — | Issuer CIK (the company being held). Accepts both 10-char zero-padded form and unpadded. Returns 404 when no filings exist linking this holder to this issuer. | 0000320193 |
| asOfDate | query | optional | — | — | Compute position AS OF this date (ISO `YYYY-MM-DD`). Default is today. The ledger replays only filings with `filedAt <= asOfDate`. Useful for historical reconstruction — 'what was Berkshire's AAPL position on Q4 2024 close?' Returns same shape as today-calculation; does NOT mark-to-market the price. | 2026-04-15 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| holderUuid | string | no | Holder UUID echoed back. Useful for asserting your client's holder-resolution mapping is correct. |
| issuerCik | string | no | Issuer CIK echoed back in 10-char zero-padded form regardless of input. |
| issuerTicker | string | yes | Resolved issuer ticker (canonical hyphen form). Null when issuer has no public-equity ticker. |
| currentShares | number | no | Net shares held by this holder in this issuer as of `asOf`. Positive = long position; 0 = position fully exited (still returned for audit trail). Computed from the event-sourced ledger replay, NOT looked up from a single filing — combines 13F base + Form 4 deltas. Split-adjusted to most recent split for clean cross-time comparison. |
| currentPercent | number | yes | Estimated `percent_of_class` when computable from the most recent 13D/13G assertion in the ledger replay. Null when only 13F + Form 4 sources contribute (since 13F doesn't carry percent-of-class — only an aggregate value). Below 5% positions typically have null `currentPercent` since they're not subject to 13D/G disclosure. |
| sourceFormTypes | array | no | Array of form types that contributed to the ledger-replay calculation (e.g. `["13F-HR", "4", "4", "13D/A"]`). Order matches chronological replay order. Use to audit the position derivation and surface 'last-13D-was-N-quarters-ago' staleness signals to consumers. |
| asOf | string | no | ISO-8601 UTC timestamp of the MOST RECENT filing contributing to the position calculation (i.e. the high-water-mark of the ledger replay). Echoes the `asOfDate` query parameter when one was passed; otherwise reflects the latest contributing filing's `filedAt`. Use to detect position staleness — if `asOf` is months old, the ledger has no fresh signal. |
| firstObservedAt | string | no | ISO-8601 UTC timestamp of the EARLIEST filing contributing to the position. Useful for tenure metrics — `asOf - firstObservedAt` is roughly the holder's holding-period in this issuer. Berkshire's AAPL position has `firstObservedAt` around 2016-Q1 (when the 13F first surfaced the position). |
Sample response
·
- "holderUuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd"
- "issuerCik": "0000320193"
- "issuerTicker": "AAPL"
- "currentShares": 905560000
- "currentPercent": 5.84
- "sourceFormTypes":
- "13F"
- "13D"
- "asOf": "2026-04-15T20:14:32.000Z"
- "firstObservedAt": "2016-05-16T20:14:32.000Z"
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/positions/{holder_uuid}/issuer/{issuer_cik}?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).