Insider Holdings

Current ownership positions reported by directors, officers, and 10% owners via Form 3/4/5 filings

GET /v1/insider-trades/holders

List insider holdings

cURL

curl --request GET \
  --url https://api.ivory.finance/v1/insider-trades/holders \
  --header 'X-API-Key: <api-key>'

200

[
  {
    "id": 123,
    "accession_number": "<string>",
    "form_type": "<string>",
    "filed_at": "2023-11-07T05:31:56Z",
    "period_of_report": "2023-12-25",
    "cik": "<string>",
    "ticker": "<string>",
    "issuer_cik": "<string>",
    "issuer_name": "<string>",
    "issuer_trading_symbol": "<string>",
    "owner_cik": "<string>",
    "owner_name": "<string>",
    "is_director": true,
    "is_officer": true,
    "is_ten_percent_owner": true,
    "is_other": true,
    "officer_title": "<string>",
    "security_title": "<string>",
    "shares_owned": 123,
    "is_derivative": true,
    "conversion_exercise_price": 123,
    "exercise_date": "2023-12-25",
    "expiration_date": "2023-12-25",
    "underlying_security_title": "<string>",
    "underlying_security_shares": 123,
    "direct_or_indirect": "<string>",
    "nature_of_ownership": "<string>",
    "created_at": "2023-11-07T05:31:56Z"
  }
]

What This Endpoint Returns

Holdings represent the static ownership snapshot reported in each Form 3/4/5 filing — both non-derivative positions (common stock, restricted shares) and derivative positions (options, warrants, convertible notes).

Field	Description
shares_owned	Total shares held as of the filing date
is_derivative	true for options/warrants; false for direct stock ownership
direct_or_indirect	D = directly owned; I = held indirectly (e.g. via trust or LLC)
nature_of_ownership	Free-text description for indirect holdings (e.g. “By Spouse”, “As Trustee”)
conversion_exercise_price	Strike price for derivative holdings
exercise_date / expiration_date	Vesting / expiry window for options and warrants

Insider Roles

Field	Meaning
is_director	Board member
is_officer	Executive (CEO, CFO, etc.) — see officer_title for the specific role
is_ten_percent_owner	Beneficial owner of ≥ 10% of outstanding shares
is_other	Other relationship (e.g. former officer, 5% owner below the 10% threshold)

Authorizations

X-API-Key · string · header · required

Query Parameters

ticker · string · required

Issuer ticker symbol (case-insensitive), e.g. AAPL

owner_name · string | null

Partial match on owner/filer name

is_derivative · boolean | null

Filter to derivative or non-derivative holdings

limit · integer · default: 100

Required range: 1 <= x <= 1000

offset · integer · default: 0

Required range: x >= 0

Response

200

application/json

Successful Response

id · integer | null

accession_number · string | null

form_type · string | null

filed_at · string<date-time> | null

period_of_report · string<date> | null

cik · string | null

ticker · string | null

issuer_cik · string | null

issuer_name · string | null

issuer_trading_symbol · string | null

owner_cik · string | null

owner_name · string | null

is_director · boolean | null

is_officer · boolean | null

is_ten_percent_owner · boolean | null

is_other · boolean | null

officer_title · string | null

security_title · string | null

shares_owned · number | null

is_derivative · boolean | null

conversion_exercise_price · number | null

exercise_date · string<date> | null

expiration_date · string<date> | null

underlying_security_title · string | null

underlying_security_shares · number | null

direct_or_indirect · string | null

nature_of_ownership · string | null

created_at · string<date-time> | null