--- title: "List SEC Form 4 transaction lines with EDGAR receipts." method: GET path: "/api/v1/insiders" tags: ["Insiders"] --- # List SEC Form 4 transaction lines with EDGAR receipts. `GET /api/v1/insiders` ## Request - Base URL: `https://www.veridionmarkets.com` - URL: `https://www.veridionmarkets.com/api/v1/insiders` - Auth: one of: - none - HTTP bearer Reads Veridion's first-party SEC EDGAR Form 4 warehouse for a window of calendar days ending at the latest parsed EDGAR daily index (through_date). Each line carries the filing's accession, issuer CIK and printed symbol, every reporting owner with relationship boxes as filed, the transaction code, date, shares, price and post-transaction holdings as filed decimal text, Table II derivative terms, footnotes, the Rule 10b5-1 checkbox, and a receipt: the SEC EDGAR URL Veridion downloaded, the primary ownership XML URL, the XML element path of the line and SHA256 hashes of the downloaded and parsed bytes. A ticker is shown only when SEC's own company directory confirms the printed symbol for the issuer CIK. classification is Veridion's label of the filed code and footnotes; open_market_buy requires code P with no plan or non-market footnote. Only original Form 4 filings are served; Form 4/A amendments and held, refused or pending filings are counted in coverage, not served. coverage reports the measured index completeness of the window, never smoothed. No price, return or score is joined. Anonymous, free and evaluator callers read the latest index day only, bounded to the same latest 25 served lines BEFORE filters, with no cursor, and consume the existing shared 60-request-per-IP hourly disclosure budget. A Developer key reads up to 7 days and pages with a signed cursor pinned to through_date and as_of; when a new index day is parsed the cursor is refused and the walk restarts. Developer remains $49/month or $490/year. ## Query parameters - `limit` integer: Default 25 on free, 100 on Developer; free maximum 25, Developer maximum 1000. - `cursor` string: Signed insiders cursor; Developer only. Preserve days and every filter. Cursors from other endpoints are refused. - `days` integer: Calendar days in the window, ending at the latest parsed EDGAR index date. Default 1; above 1 requires a Developer key. - `filed_date` string: Exact EDGAR filing date (YYYY-MM-DD) within the window. On free access this filters the fixed recent window. - `ticker` string: Issuer symbol as printed or as confirmed by SEC's company directory; case-insensitive, '-' and '/' read as '.'. - `issuer_cik` string: Issuer SEC CIK; leading zeros optional. - `reporting_owner_cik` string: Reporting owner SEC CIK; matches any owner on a joint filing. - `classification` 'open_market_buy' | 'sale' | 'award' | 'other_transaction' | 'exercise' | 'tax_withholding' | 'dividend_reinvestment' | 'planned_trade' | 'plan_status_unresolved' | 'footnote_unresolved' | 'code_unresolved' | 'other_code': Veridion classification of the filed transaction code and footnotes. ## Response `200` Form 4 lines with measured window coverage, held reasons and access window. - InsiderPage: A page of first-party SEC Form 4 transaction lines with measured window coverage, access and cache contracts. - `computed_at` string, date-time, required: This response's computation time; not a filing, collection or index time. - `version` string, required: Served Disclosure API contract version, also sent as X-API-Version. - `coverage` object, required: Measured EDGAR index coverage for the window, never smoothed, plus response-local counts. - `rows_returned` integer, required: Lines returned in this response after caller filters; not a warehouse total. - `rows_held` integer, required: Window lines withheld from this response because they failed the identity or receipt contract. - `held_by_reason` object, required: Per-reason count of withheld lines. - `window_days` integer, required: Calendar days read, ending at through_date. - `start_date` string, required: First calendar day of the window, YYYY-MM-DD. - `through_date` string, required: Latest parsed EDGAR daily index date; the window ends here. - `as_of` string, date-time, required: Latest index or filing observation instant behind the window. A cursor pins it, so later observations wait for a new walk. - `complete` boolean, required: True only when every index day in the window was read and no listed filing is still pending. - `reason` 'complete' | 'index_days_missing' | 'filings_pending', required: Why complete is true or false, exactly as measured. - `missing_index_dates` string[], required: Window days with no readable EDGAR daily index. - `not_listed_dates` string[], required: Window days EDGAR published no daily index for, such as weekends and holidays. - `indexed_accessions` integer, required: Form 4 and 4/A accessions listed on the window's EDGAR daily indexes. - `parsed_filings` integer, required: Listed filings parsed and available for serving. - `held_filings` integer, required: Listed filings held from serving, including every Form 4/A. - `refused_filings` integer, required: Listed filings the parser refused. - `pending_filings` integer, required: Listed filings not yet collected. - `window_lines` integer, required: Served lines in the whole window before access limits and caller filters. - `basis` string, required: Scope of the served population; no claim about filings outside the window. - `page` object, required: Keyset pagination within one pinned EDGAR window. - `limit` integer, required: Requested page size under the verified access mode. - `has_more` boolean, required: Another matching line follows in the same pinned window. Always false on the free window. - `next_cursor` string, nullable, required: Signed, query-bound position for the next Developer page, or null. Refused once through_date advances. - `order` 'filing_date_desc', required: Filing date descending, then accession, ownership table and line ascending; not a ranking. - `access` object, required: Verified access mode and its row, window and request limits. - `tier` 'free' | 'developer', required: Effective access mode. Only Developer keys page or read more than one day. - `max_rows_per_request` integer, required: Allowed page size: 25 on the free window, 1000 on Developer. - `max_window_days` integer, required: Calendar days a request may read: 1 on the free window, 7 on Developer. - `window_rows` integer: Free window size: the latest 25 served lines before caller filters; omitted for Developer. - `window_basis` string: How the free window is selected. Filters narrow it and never widen it. - `requests_per_hour_per_ip` integer: Shared hourly anonymous disclosure budget per IP. - `cache` object, required: Executable delivery-cache contract matching the private no-store headers. - `policy` 'private-no-store', required: Caller-specific origin response; not reusable by a browser or shared cache. - `browser_max_age_seconds` 0, required: Browser cache lifetime in seconds: zero. - `cdn_max_age_seconds` 0, required: Shared CDN cache lifetime in seconds: zero. - `declared_max_staleness_seconds` 0, required: Delivery staleness allowance in seconds: zero; source instants remain distinct. - `age_header` unknown, required - `notice` string, required: As-filed and non-recommendation notice. - `data` object[], required: Served Form 4 transaction lines in this page. - `line_id` string, required: Stable line identity: accession, ownership table and the one-based line within that table, as printed in the filing XML. - `content_hash` string, required: SHA256 hex of the UTF-8 JSON of every served field except content_hash and provenance, keys sorted at every level, no whitespace. - `content_hash_basis` 'veridion-sec-form4-content-v1', required: Named hash recipe. Collection and parse clocks are provenance and never change content_hash. - `accession` string, required: SEC accession number of the Form 4 filing. - `form_type` '4', required: SEC form type. Only original Form 4 filings are served; Form 4/A amendments are held, not served. - `filing_date` string, required: EDGAR filing date, YYYY-MM-DD; not the transaction date or Veridion's collection date. - `issuer` object, required: The issuer exactly as identified by the filing. - `cik` string, required: Issuer Central Index Key as filed, ten digits. - `name` string, nullable, required: Issuer name as printed in the filing XML. - `trading_symbol` string, nullable, required: Issuer trading symbol exactly as printed in the filing; null when the filing omits it. - `ticker_mapping` object, nullable, required: SEC's own confirmation that the printed symbol belongs to this issuer CIK, or null. A ticker is never inferred from a name. - `ticker` string, required: Printed symbol normalized (uppercase; '-' and '/' become '.') and confirmed for this CIK by SEC's company directory. - `printed_ticker` string, required: The ticker exactly as SEC's company directory prints it. - `source_url` string, required: SEC company directory URL the confirmation was read from. - `fetched_at` string, date-time, required: When Veridion retrieved that SEC directory, UTC. - `sha256` string, required: SHA256 of the SEC directory bytes Veridion retrieved. - `reporting_owners` object[], required: Every reporting owner on the filing, in filing order. Owners are filing-level: the form does not attribute a line to one owner of a joint filing. - `cik` string, nullable, required: Reporting owner Central Index Key as filed. - `name` string, nullable, required: Reporting owner name as printed in the filing. - `director` boolean, nullable, required: Director box as filed; null when the filing leaves it unstated. - `officer` boolean, nullable, required: Officer box as filed; null when unstated. - `officer_title` string, nullable, required: Officer title as printed, or null. - `ten_percent_owner` boolean, nullable, required: 10% owner box as filed; null when unstated. - `other` boolean, nullable, required: Other relationship box as filed; null when unstated. - `other_text` string, nullable, required: Other relationship text as printed, or null. - `security_title` string, nullable, required: Security title as printed on this line. - `ownership_table` 'derivative' | 'non_derivative', required: Form 4 table the line is printed in: Table I (non_derivative) or Table II (derivative). - `line` integer, required: One-based line within its table, in filing order. - `transaction` object, required: The transaction line exactly as filed, plus Veridion's code classification. - `code` string, nullable, required: SEC transaction code as filed (for example P, S, A, M, F). - `date` string, nullable, required: Transaction date as filed, YYYY-MM-DD; null when absent or not a calendar date (see value_exceptions). - `classification` 'open_market_buy' | 'sale' | 'award' | 'other_transaction' | 'exercise' | 'tax_withholding' | 'dividend_reinvestment' | 'planned_trade' | 'plan_status_unresolved' | 'footnote_unresolved' | 'code_unresolved' | 'other_code', required: Veridion classification of the filed code and footnotes. open_market_buy requires code P with no plan or non-market footnote; unresolved cases are labelled, never guessed. - `shares` string, nullable, required: Shares or units exactly as filed, decimal text, never a float. - `price_per_share` string, nullable, required: Price per share exactly as filed, decimal text; null when absent or given only in a footnote. - `acquired_disposed` 'A' | 'D', nullable, required: Acquired (A) or disposed (D) as filed. - `shares_owned_after` string, nullable, required: Shares beneficially owned after the transaction, exactly as filed. - `direct_indirect` 'D' | 'I', nullable, required: Direct (D) or indirect (I) ownership as filed. - `nature_of_ownership` string, nullable, required: Nature of indirect ownership as printed (for example a trust), or null. - `derivative` object, nullable, required: Table II derivative terms as filed; null for Table I lines. - `conversion_or_exercise_price` string, nullable, required: Conversion or exercise price as filed. - `exercise_date` string, nullable, required: Date exercisable as filed, YYYY-MM-DD. - `expiration_date` string, nullable, required: Expiration date as filed, YYYY-MM-DD. - `underlying_security_title` string, nullable, required: Underlying security title as filed. - `underlying_security_shares` string, nullable, required: Underlying shares as filed, decimal text. - `value_exceptions` object[], required: Fields served as null because the filing states them only in a footnote or prints them in an unreadable form. Absent fields are not listed. - `field` 'security_title' | 'transaction_code' | 'transaction_date' | 'shares' | 'price' | 'acquired_disposed' | 'owned_after' | 'direct_indirect' | 'nature_of_ownership' | 'conversion_or_exercise_price' | 'exercise_date' | 'expiration_date' | 'underlying_security_title' | 'underlying_security_shares', required: Filing field served as null on this line. - `state` 'footnote_only' | 'unparseable', required: footnote_only: the filing gives this value only in a footnote. unparseable: the printed value is not in the field's expected form. - `raw` string, nullable, required: The printed text for an unparseable value, exactly as filed; null for footnote_only. - `rule_10b5_1` boolean, nullable, required: The filing's Rule 10b5-1 checkbox as filed; null when the form does not carry it. - `footnotes` object[], required: Footnotes the filing attaches to this line, one entry per reference. - `id` string, required: Footnote identifier as printed (for example F1). - `text` string, required: Footnote text exactly as filed. - `field_locator` string, nullable, required: XML path of the field the footnote is attached to. - `receipt` object, required: The government's own record behind this line, with exact hashes for independent re-verification. - `url` string, required: SEC EDGAR URL of the bytes Veridion downloaded; the full submission when hash_kind is embedded_xml. - `primary_document_url` string, required: SEC EDGAR URL of the filing's primary ownership XML. - `primary_document_verified` boolean, required: True only when Veridion downloaded and hashed the primary document URL itself; false when the XML was read from the submission. - `index_url` string, nullable, required: SEC EDGAR filing index page. - `xml_locator` string, required: Exact element path of this line inside the ownership XML. - `document_sha256` string, required: SHA256 of the exact ownership XML bytes Veridion parsed. - `document_byte_length` integer, required: Byte length of that ownership XML. - `hash_kind` 'document' | 'embedded_xml', required: document: the primary XML was hashed as downloaded. embedded_xml: the XML was extracted from the downloaded submission, then hashed. - `source_sha256` string, required: SHA256 of the bytes downloaded from receipt.url. - `source_byte_length` integer, required: Byte length of the bytes downloaded from receipt.url. - `provenance` object, required: Collection evidence. This response's computed_at never replaces these clocks. - `first_observed_at` string, date-time, required: When Veridion first observed the filing, UTC; outside content_hash. - `recorded_at` string, date-time, required: When Veridion recorded this parse, UTC. - `parser_version` string, required: Parser version that produced the line. ## Other responses - `400`: Invalid parameter, date or cursor, including a cursor from an earlier window. - `401`: The supplied bearer key is invalid; it is never downgraded to anonymous. - `403`: Missing disclosure scope, or a cursor or multi-day window without a Developer key. - `429`: An enforced request budget was exceeded. - `503`: The warehouse, its index measurement, quota or cursor signing could not be verified. --- [API](https://skmtc.dev/veridionmarkets/apis/veridion-disclosure-api.md) · [All operations](https://skmtc.dev/veridionmarkets/apis/veridion-disclosure-api/llms.txt) · [OpenAPI document](https://skmtc.dev/veridionmarkets/apis/veridion-disclosure-api/revisions/af69a5d7354e?raw)