Skip to main content
GET
/
v1
/
insider-trades
/
holders
List insider holdings
curl --request GET \
  --url https://api.ivory.finance/v1/insider-trades/holders \
  --header 'X-API-Key: <api-key>'
[
  {
    "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"
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
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).
FieldDescription
shares_ownedTotal shares held as of the filing date
is_derivativetrue for options/warrants; false for direct stock ownership
direct_or_indirectD = directly owned; I = held indirectly (e.g. via trust or LLC)
nature_of_ownershipFree-text description for indirect holdings (e.g. “By Spouse”, “As Trustee”)
conversion_exercise_priceStrike price for derivative holdings
exercise_date / expiration_dateVesting / expiry window for options and warrants

​
Insider Roles

FieldMeaning
is_directorBoard member
is_officerExecutive (CEO, CFO, etc.) — see officer_title for the specific role
is_ten_percent_ownerBeneficial owner of ≥ 10% of outstanding shares
is_otherOther 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

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