InsiderFilings API

openapi: 3.1.0
info:
  title: InsiderFilings API v1 — Public Beta
  version: 1.1.1-beta
  description: >-
    Public Beta REST API for normalized SEC ownership transaction line items
    from Forms 3, 4 and 5, including amendments. Response fields, filters and
    rate limits may change during the beta. Coverage from 2025 onward is
    intended to be complete and reconciled; older historical coverage may be
    incomplete. New SEC ownership filings are typically checked about every
    five minutes, but no freshness or availability SLA is provided. Data may
    contain parsing errors or delays. Important information should be verified
    against the original SEC filing; SEC filings remain authoritative. Decimal
    values are returned as strings to preserve precision. A null value means
    unavailable or not represented and is not equivalent to numeric zero. All
    *_to date and timestamp filters are exclusive.
servers:
  - url: https://insiderfilings.info/api/v1
paths:
  /:
    get:
      operationId: getApiStatus
      summary: API information and availability
      security: []
      responses:
        '200':
          description: API information
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    additionalProperties: true
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
  /transactions:
    get:
      operationId: listTransactions
      summary: List SEC ownership transaction line items
      description: >-
        Returns transaction line items in accepted_at DESC, filing_id DESC,
        line_item_id DESC order. If cursor is supplied, it must be the only
        query parameter. The filing snapshot does not freeze issuer profile
        updates; SIC data and results filtered by SIC can change between pages.
        Self-service trial keys, when enabled, expire 7 days after activation,
        allow 100 requests per UTC calendar day and 10 per fixed minute, and
        cover only filings accepted within the last 30 days. Historical access
        bounds are enforced on every page independently of filters and cursors.
        Personal pilot keys retain their existing permissions and quotas.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Ticker'
        - $ref: '#/components/parameters/IssuerCik'
        - $ref: '#/components/parameters/Accession'
        - $ref: '#/components/parameters/Form'
        - $ref: '#/components/parameters/TransactionCode'
        - $ref: '#/components/parameters/AcquiredDisposed'
        - $ref: '#/components/parameters/LineType'
        - $ref: '#/components/parameters/OwnerCik'
        - $ref: '#/components/parameters/OwnerName'
        - $ref: '#/components/parameters/OwnerRole'
        - $ref: '#/components/parameters/Sic'
        - $ref: '#/components/parameters/ForeignSymbol'
        - $ref: '#/components/parameters/AcceptedFrom'
        - $ref: '#/components/parameters/AcceptedTo'
        - $ref: '#/components/parameters/FiledFrom'
        - $ref: '#/components/parameters/FiledTo'
        - $ref: '#/components/parameters/TransactionFrom'
        - $ref: '#/components/parameters/TransactionTo'
        - $ref: '#/components/parameters/MinValue'
        - $ref: '#/components/parameters/MaxValue'
        - $ref: '#/components/parameters/PriceStatus'
      responses:
        '200':
          description: Transaction page
          headers:
            X-API-Version:
              schema: {type: string}
            X-Request-ID:
              schema: {type: string}
            RateLimit-Limit:
              schema: {type: integer}
            RateLimit-Remaining:
              schema: {type: integer}
            RateLimit-Reset:
              description: Seconds until the current window resets.
              schema: {type: integer}
            X-Trial-Daily-Limit:
              description: Daily trial quota; present only for trial keys.
              schema: {type: integer}
            X-Trial-Daily-Remaining:
              schema: {type: integer}
            X-Trial-Daily-Reset:
              description: UTC Unix timestamp of the next calendar day.
              schema: {type: integer}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key supplied in X-API-Key. Personal pilot keys are issued manually.
        When enabled, temporary trial keys are obtained at /api/v1/trial/ after
        email verification. The key is displayed once; trial access is limited
        to transactions. No automatic renewal; one trial per email per 90 days.
  parameters:
    Limit:
      name: limit
      in: query
      description: Rows per page. Not allowed together with cursor.
      schema: {type: integer, minimum: 1, maximum: 100, default: 50}
    Cursor:
      name: cursor
      in: query
      description: Opaque signed cursor from pagination.next_cursor. Must be the only query parameter.
      schema: {type: string, maxLength: 8192}
    Ticker:
      name: ticker
      in: query
      description: Comma-separated issuer ticker symbols.
      schema: {type: array, maxItems: 100, items: {type: string}}
      style: form
      explode: false
    IssuerCik:
      name: issuer_cik
      in: query
      description: Comma-separated issuer CIKs.
      schema: {type: array, maxItems: 100, items: {type: string}}
      style: form
      explode: false
    Accession:
      name: accession
      in: query
      description: Comma-separated SEC accession numbers.
      schema: {type: array, maxItems: 100, items: {type: string}}
      style: form
      explode: false
    Form:
      name: form
      in: query
      description: >-
        Comma-separated SEC ownership form types. Amendments (3/A, 4/A and 5/A)
        are returned as distinct filings and are not collapsed into the original filing.
      schema:
        type: array
        maxItems: 100
        items: {type: string, enum: ['3', '3/A', '4', '4/A', '5', '5/A']}
      style: form
      explode: false
    TransactionCode:
      name: transaction_code
      in: query
      description: Comma-separated SEC transaction codes such as P, S, A or M.
      schema: {type: array, maxItems: 100, items: {type: string}}
      style: form
      explode: false
    AcquiredDisposed:
      name: acquired_disposed
      in: query
      schema:
        type: array
        maxItems: 2
        items: {type: string, enum: [A, D]}
      style: form
      explode: false
    LineType:
      name: line_type
      in: query
      schema:
        type: array
        maxItems: 2
        items:
          type: string
          enum: [non_derivative_transaction, derivative_transaction]
      style: form
      explode: false
    OwnerCik:
      name: owner_cik
      in: query
      description: Comma-separated reporting-owner CIKs.
      schema: {type: array, maxItems: 100, items: {type: string}}
      style: form
      explode: false
    OwnerName:
      name: owner_name
      in: query
      description: Comma-separated case-insensitive owner-name substrings.
      schema: {type: array, maxItems: 100, items: {type: string}}
      style: form
      explode: false
    OwnerRole:
      name: owner_role
      in: query
      schema:
        type: array
        maxItems: 100
        items:
          type: string
          enum: [ceo, cfo, cao, director, officer, ten_percent_owner, other]
      style: form
      explode: false
    ForeignSymbol:
      name: foreign_symbol
      in: query
      description: >-
        Filing-level reported foreign trading symbol, filtered before pagination.
        present excludes blanks and N/A, NA, NONE, NOT APPLICABLE (case insensitive).
        missing is the complement. This is an observed filing marker, not verified
        foreign-private-issuer status or a determination of exemptions.
      schema: {type: string, enum: [any, present, missing], default: any}
    Sic:
      name: sic
      in: query
      description: >-
        Filter by current issuer-profile SIC coverage before pagination.
        present requires a nonblank SIC code. missing includes both an absent
        issuer profile and a profile with an empty SIC code. This does not
        verify exchange listing or the security class traded.
      schema: {type: string, enum: [any, present, missing], default: any}
    AcceptedFrom:
      name: accepted_from
      in: query
      description: >-
        Inclusive lower boundary for the SEC acceptance timestamp. accepted_at is
        exposed in UTC; this is distinct from filed_date and transaction_date.
      schema: {type: string, format: date-time}
    AcceptedTo:
      name: accepted_to
      in: query
      description: >-
        Exclusive upper boundary for the SEC acceptance timestamp. accepted_at is
        exposed in UTC; this is distinct from filed_date and transaction_date.
      schema: {type: string, format: date-time}
    FiledFrom:
      name: filed_from
      in: query
      description: >-
        Inclusive lower boundary for the SEC filing date, interpreted in
        America/New_York. This is distinct from accepted_at and transaction_date.
      schema: {type: string, format: date}
    FiledTo:
      name: filed_to
      in: query
      description: >-
        Exclusive upper boundary for the SEC filing date, interpreted in
        America/New_York. This is distinct from accepted_at and transaction_date.
      schema: {type: string, format: date}
    TransactionFrom:
      name: transaction_from
      in: query
      description: >-
        Inclusive lower boundary for the transaction date reported on the
        transaction line. This is distinct from filed_date and accepted_at.
      schema: {type: string, format: date}
    TransactionTo:
      name: transaction_to
      in: query
      description: >-
        Exclusive upper boundary for the transaction date reported on the
        transaction line. This is distinct from filed_date and accepted_at.
      schema: {type: string, format: date}
    MinValue:
      name: min_value
      in: query
      description: Inclusive minimum effective transaction value.
      schema: {type: string, pattern: '^-?[0-9]+(?:\.[0-9]+)?$'}
    MaxValue:
      name: max_value
      in: query
      description: Inclusive maximum effective transaction value.
      schema: {type: string, pattern: '^-?[0-9]+(?:\.[0-9]+)?$'}
    PriceStatus:
      name: price_status
      in: query
      description: >-
        Filter by the stored price-quality detector status. NORMAL means the
        reported price was accepted by the current detector. CORRECTED means an
        accepted high-confidence normalized replacement is used as the effective
        price. REVIEW means the anomaly remains unresolved and the price should not
        be treated as validated for automated use. INVALID and NOT_APPLICABLE are
        detector classifications. A row with price.quality = null has no matching
        current detector record and must not be treated as NORMAL.
      schema:
        type: array
        maxItems: 100
        items:
          type: string
          enum: [CORRECTED, INVALID, NORMAL, NOT_APPLICABLE, REVIEW]
      style: form
      explode: false
  responses:
    BadRequest:
      description: Invalid request or cursor
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorResponse'}
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorResponse'}
    MethodNotAllowed:
      description: Unsupported HTTP method
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorResponse'}
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema: {type: integer}
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorResponse'}
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorResponse'}
    Unavailable:
      description: API, configuration or rate limiter unavailable
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorResponse'}
  schemas:
    NullableString:
      type: [string, 'null']
    Decimal:
      type: [string, 'null']
      description: >-
        Decimal encoded as a string to preserve precision. null means unavailable
        or not represented; it is not equivalent to numeric zero.
      pattern: '^-?[0-9]+(?:\.[0-9]+)?$'
    ResponseMeta:
      type: object
      required: [request_id, generated_at]
      properties:
        request_id: {type: string}
        generated_at: {type: string, format: date-time}
      additionalProperties: true
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, request_id]
          properties:
            code: {type: string}
            message: {type: string}
            request_id: {type: string}
            details: {type: object, additionalProperties: true}
    TransactionsResponse:
      type: object
      required: [data, pagination, meta]
      properties:
        data:
          type: array
          items: {$ref: '#/components/schemas/TransactionRow'}
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          type: object
          required: [api_version, request_id, generated_at, sort, filters, price_detector_version]
          properties:
            api_version: {type: string, const: v1}
            request_id: {type: string}
            generated_at: {type: string, format: date-time}
            sort: {type: object, additionalProperties: {type: string}}
            filters: {type: object, additionalProperties: true}
            price_detector_version: {type: string}
    Pagination:
      type: object
      required: [limit, returned, has_more, next_cursor, snapshot_filing_id]
      properties:
        limit: {type: integer, minimum: 1, maximum: 100}
        returned: {type: integer, minimum: 0}
        has_more: {type: boolean}
        next_cursor: {type: [string, 'null']}
        snapshot_filing_id: {type: integer, minimum: 1}
    TransactionRow:
      type: object
      required: [line_item_id, filing, issuer, transaction, price, ownership_after, owners, owner_attribution, footnote_context]
      properties:
        line_item_id: {type: integer}
        filing: {$ref: '#/components/schemas/Filing'}
        issuer: {$ref: '#/components/schemas/Issuer'}
        transaction: {$ref: '#/components/schemas/Transaction'}
        price: {$ref: '#/components/schemas/Price'}
        ownership_after: {$ref: '#/components/schemas/OwnershipAfter'}
        owners:
          type: array
          description: Reporting owners of the filing; they are not necessarily each attributable to this transaction line.
          items: {$ref: '#/components/schemas/Owner'}
        owner_attribution: {$ref: '#/components/schemas/OwnerAttribution'}
        footnote_context: {$ref: '#/components/schemas/FootnoteContext'}
    FootnoteContext:
      type: object
      description: >-
        Observed SEC footnote text and its source. No automated finding that a
        purchase was made under a trading plan or offering. Footnotes linked
        only to other transaction lines are not attached to this line.
      required: [coverage, parser_version, checked_at, line_footnotes, unlinked_filing_footnotes, filing_remarks]
      properties:
        coverage:
          type: string
          enum: [parsed_current, not_verified_current]
          description: >-
            parsed_current requires parser version ownership-2026-08-15.1 and
            footnotes_checked_at. It confirms processing with this parser version,
            not independent verification of interpretation or historical line identity.
        parser_version: {$ref: '#/components/schemas/NullableString'}
        checked_at: {type: [string, 'null'], format: date-time}
        line_footnotes:
          type: array
          description: Footnotes with an XML reference on this exact line and field.
          items: {$ref: '#/components/schemas/LineFootnote'}
        unlinked_filing_footnotes:
          type: array
          description: >-
            Footnotes defined in this filing without a reference on any line.
            Their applicability to this transaction is unknown.
          items: {$ref: '#/components/schemas/UnlinkedFootnote'}
        filing_remarks: {$ref: '#/components/schemas/NullableString'}
    LineFootnote:
      type: object
      required: [footnote_id, text, field_name, xml_path]
      properties:
        footnote_id: {type: string}
        text: {type: string}
        field_name: {type: string}
        xml_path: {type: string}
    UnlinkedFootnote:
      type: object
      required: [footnote_id, text]
      properties:
        footnote_id: {type: string}
        text: {type: string}
    OwnerAttribution:
      type: object
      description: >-
        A unique line owner is inferred only when the filing has exactly one reporting owner
        with a CIK. Multiple-owner filings cannot be attributed to a specific transaction
        line from filing_owners alone. Role flags in owners are reported at filing level.
      required: [status, owner_cik]
      properties:
        status:
          type: string
          enum: [unique, missing_cik, multiple_owners, missing_owner]
        owner_cik: {$ref: '#/components/schemas/NullableString'}
    Filing:
      type: object
      required: [id, accession_no, source_kind, form_type, filed_date, accepted_at, accepted_date_ny, period_of_report, ingested_at, urls]
      properties:
        id: {type: integer}
        accession_no: {type: string}
        source_kind: {type: string}
        form_type:
          type: string
          description: >-
            SEC ownership form type. Forms 3/A, 4/A and 5/A are amendments and are
            returned as separate filings rather than merged into the original.
        issuer_foreign_trading_symbol:
          $ref: '#/components/schemas/NullableString'
        filed_date:
          type: string
          format: date
          description: SEC filing date interpreted in America/New_York.
        accepted_at:
          type: [string, 'null']
          format: date-time
          description: SEC acceptance timestamp exposed in UTC; null when unavailable.
        accepted_date_ny:
          type: [string, 'null']
          format: date
          description: Date of accepted_at in America/New_York; null when accepted_at is absent.
        period_of_report: {type: [string, 'null'], format: date}
        ingested_at: {type: [string, 'null'], format: date-time}
        urls:
          type: object
          required: [insiderfilings, sec_filing, sec_index, sec_xml]
          properties:
            insiderfilings: {$ref: '#/components/schemas/NullableString'}
            sec_filing: {$ref: '#/components/schemas/NullableString'}
            sec_index: {$ref: '#/components/schemas/NullableString'}
            sec_xml: {$ref: '#/components/schemas/NullableString'}
    Issuer:
      type: object
      required: [cik, ticker, name]
      properties:
        cik: {type: string}
        ticker: {$ref: '#/components/schemas/NullableString'}
        name: {type: string}
        business_location:
          type: [string, 'null']
          description: >-
            Display label for the business address in the current stored SEC
            issuer profile, using the same formatter as ticker pages. May contain
            city and country or U.S. state; not independently verified headquarters,
            legal domicile, or foreign-private-issuer status. Not historical filing
            data. Null when location information is unavailable.
        sic: {$ref: '#/components/schemas/IssuerSic'}
    IssuerSic:
      type: object
      description: >-
        Current issuer-level SEC profile data. Not evidence that the reported
        security class is exchange listed. derived_sector is a local mapping,
        not a separate SEC classification.
      required: [coverage, code, description, derived_sector]
      properties:
        coverage:
          type: string
          enum: [available, sic_missing, profile_missing]
        code: {$ref: '#/components/schemas/NullableString'}
        description: {$ref: '#/components/schemas/NullableString'}
        derived_sector: {$ref: '#/components/schemas/NullableString'}
    Transaction:
      type: object
      required: [line_no, line_type, security_title, transaction_date, filing_delay_calendar_days, deemed_execution_date, transaction_code, is_equity_swap_involved, shares, acquired_disposed, timeliness, derivative]
      properties:
        line_no: {type: integer}
        line_type: {type: string, enum: [non_derivative_transaction, derivative_transaction]}
        security_title: {$ref: '#/components/schemas/NullableString'}
        transaction_date:
          type: [string, 'null']
          format: date
          description: Transaction date reported on this SEC transaction line.
        filing_delay_calendar_days:
          type: [integer, 'null']
          minimum: 0
          description: >-
            Calendar days from this line's reported transaction_date to filing.accepted_date_ny.
            Null if either date is missing or invalid, or the transaction date follows acceptance.
            This is not an assessment of regulatory timeliness and does not apply a seven-day filter.
        deemed_execution_date: {type: [string, 'null'], format: date}
        transaction_code: {$ref: '#/components/schemas/NullableString'}
        is_equity_swap_involved: {type: boolean}
        shares: {$ref: '#/components/schemas/Decimal'}
        acquired_disposed: {type: [string, 'null'], enum: [A, D, null]}
        timeliness: {$ref: '#/components/schemas/NullableString'}
        derivative:
          type: object
          required: [underlying_security_title, underlying_shares, exercise_price, exercise_date, expiration_date, underlying_security_value]
          properties:
            underlying_security_title: {$ref: '#/components/schemas/NullableString'}
            underlying_shares: {$ref: '#/components/schemas/Decimal'}
            exercise_price: {$ref: '#/components/schemas/Decimal'}
            exercise_date: {type: [string, 'null'], format: date}
            expiration_date: {type: [string, 'null'], format: date}
            underlying_security_value: {$ref: '#/components/schemas/Decimal'}
    Price:
      type: object
      description: >-
        Reported SEC price plus the current price-quality normalization result.
        Consumers should use effective for calculations rather than choosing between
        reported and normalized themselves.
      required: [reported, normalized, effective, adjusted, effective_transaction_value, stored_transaction_total_value, quality]
      properties:
        reported:
          allOf: [{$ref: '#/components/schemas/Decimal'}]
          description: Price reported in the SEC filing, preserved without correction.
        normalized:
          allOf: [{$ref: '#/components/schemas/Decimal'}]
          description: Accepted detector-produced normalized replacement when available.
        effective:
          allOf: [{$ref: '#/components/schemas/Decimal'}]
          description: >-
            Price selected by the API for calculations. An accepted correction uses
            normalized; otherwise the reported SEC price is retained.
        adjusted:
          type: boolean
          description: True when effective uses an accepted normalized correction instead of reported.
        effective_transaction_value:
          allOf: [{$ref: '#/components/schemas/Decimal'}]
          description: Transaction value calculated from the effective price when calculable.
        stored_transaction_total_value:
          allOf: [{$ref: '#/components/schemas/Decimal'}]
          description: Stored transaction total value when present in the normalized data model.
        quality:
          type: [object, 'null']
          description: >-
            Matching current price-quality detector record. null means no matching
            current detector assessment and must not be interpreted as NORMAL.
          additionalProperties: true
    OwnershipAfter:
      type: object
      description: Ownership information reported after the transaction on this line.
      required: [shares, ownership_type, nature, value]
      properties:
        shares: {$ref: '#/components/schemas/Decimal'}
        ownership_type:
          allOf: [{$ref: '#/components/schemas/NullableString'}]
          description: >-
            Reported ownership form, typically D for direct or I for indirect ownership.
            This describes ownership, not whether the transaction itself is discretionary.
        nature:
          allOf: [{$ref: '#/components/schemas/NullableString'}]
          description: Reported nature of indirect ownership when provided.
        value: {$ref: '#/components/schemas/Decimal'}
    Owner:
      type: object
      required: [cik, name, is_director, is_officer, is_ten_percent_owner, is_other, officer_title]
      properties:
        cik: {$ref: '#/components/schemas/NullableString'}
        name: {type: string}
        is_director: {type: boolean}
        is_officer: {type: boolean}
        is_ten_percent_owner: {type: boolean}
        is_other: {type: boolean}
        officer_title: {$ref: '#/components/schemas/NullableString'}