NZXplorer Insider Trades API

Director share transactions, substantial shareholders, and beneficial ownership

GitHub OpenAPI

Operations 9

GET /insider-trades Insider Trades #
GET /deal-insider-signals/{ticker} Deal Insider Signals #
GET /shareholders/{ticker} Shareholders #
GET /substantial-holders/{ticker} Substantial Holders #
GET /substantial-holders/{ticker}/notices SPH Notices #
GET /beneficial-ownership/{ticker} Beneficial Ownership #
GET /zapier/triggers/insider-trades Zapier: New Insider Trade #
POST /quarterly-ownership-report Quarterly Ownership Report #
GET /insider-correlation/{ticker} Insider-Announcement Correlation #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nzxplorer-co-nz:nzxplorer-co-nz-insider-trades-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

nzxplorer-co-nz-insider-trades-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: NZXplorer Insider Trades API
  version: 1.157.0
  description: 'Comprehensive NZX market data, governance intelligence, and proxy advisory API covering 130 issuers on the New Zealand Exchange. Provides structured access to company fundamentals, director intelligence, insider trades, financial statements, ESG data, dividend analytics, proxy advisory reports, and more.


    All monetary values in financial statement endpoints (income_statements, balance_sheets, cash_flow_statements, earnings_results) are in NZD thousands unless otherwise noted. Dividends per share (dps_cents) are in cents. Ratios are unit-free percentages.'
  contact:
    name: NZXplorer API Support
    email: hello@nzxplorer.co.nz
    url: https://nzxplorer.co.nz/developers
  license:
    name: Proprietary
    url: https://nzxplorer.co.nz/terms
  x-logo:
    url: https://nzxplorer.co.nz/logo.png
servers:
- url: https://nzxplorer.co.nz/api/v1
  description: Production
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Insider Trades
  description: Director share transactions, substantial shareholders, and beneficial ownership
paths:
  /insider-trades:
    get:
      operationId: listInsiderTrades
      summary: Insider Trades
      description: Director share transactions — 9,400+ buy/sell/exercise records across 10 years (2017-2026). See who is buying and selling NZX stocks. Supports cursor-based pagination via ?after= and ?before= params — responses include meta.next_cursor, meta.prev_cursor, and meta.has_more when using cursor mode.
      tags:
      - Insider Trades
      x-tier: free
      parameters:
      - name: from
        in: query
        required: false
        description: Start date (YYYY-MM-DD)
        schema:
          type: string
      - name: to
        in: query
        required: false
        description: End date (YYYY-MM-DD)
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: 'Results per page, max 500 (default: 50)'
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: 'Pagination offset (default: 0)'
        schema:
          type: integer
      - name: after
        in: query
        required: false
        description: Cursor for next page (from meta.next_cursor). Switches to cursor-based pagination mode.
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Cursor for previous page (from meta.prev_cursor). Switches to cursor-based pagination mode.
        schema:
          type: string
      responses:
        '200':
          description: Insider Trades
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /deal-insider-signals/{ticker}:
    get:
      operationId: getDealInsiderSignal
      summary: Deal Insider Signals
      description: Detect insider trading patterns before capital raises and takeovers. Cross-references director share transactions with deal announcements to flag pre-deal buying or selling within a configurable window. Use ticker
      tags:
      - Insider Trades
      x-tier: free
      parameters:
      - name: ticker
        in: path
        required: true
        description: 'Path parameter: ticker'
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: 'Lookback window: 30, 60, or 90 days (default 90)'
        schema:
          type: number
      - name: deal_type
        in: query
        required: false
        description: 'Filter: capital_raise or takeover'
        schema:
          type: string
      responses:
        '200':
          description: Deal Insider Signals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /shareholders/{ticker}:
    get:
      operationId: getShareholder
      summary: Shareholders
      description: Top 20 shareholders with ownership concentration metrics (HHI index), holder type classification (nominee/company/individual/trust/fund), year-over-year ownership changes. 8,594 records across 101 issuers with multi-year history (2010-2026). Includes substantial holders (5%+) in response.
      tags:
      - Insider Trades
      x-tier: free
      parameters:
      - name: ticker
        in: path
        required: true
        description: NZX ticker symbol
        schema:
          type: string
      - name: year
        in: query
        required: false
        description: Fiscal year filter (e.g. 2025)
        schema:
          type: string
      - name: all
        in: query
        required: false
        description: Return all years of shareholder data
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Shareholders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /substantial-holders/{ticker}:
    get:
      operationId: getSubstantialHolder
      summary: Substantial Holders
      description: ~267 substantial shareholders (5%+ voting rights) from NZX disclosure notices. Entity name/type, voting rights %, shares held, director/executive flags, disclosure dates, threshold crossing history. Supports ?include_ceased=true for former holders.
      tags:
      - Insider Trades
      x-tier: free
      parameters:
      - name: ticker
        in: path
        required: true
        description: NZX ticker symbol
        schema:
          type: string
      - name: include_ceased
        in: query
        required: false
        description: Include former holders who dropped below 5%
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Substantial Holders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /substantial-holders/{ticker}/notices:
    get:
      operationId: getSubstantialHolderNotices
      summary: SPH Notices
      description: 9,704 classified SHINTR announcements. Substantial holder notices with holder name, type, percentage, direction (increase/decrease/initial/ceased), and fund manager cross-reference. Real-time ownership change signals between semi-annual filings.
      tags:
      - Insider Trades
      x-tier: free
      parameters:
      - name: ticker
        in: path
        required: true
        description: NZX ticker symbol
        schema:
          type: string
      - name: holder
        in: query
        required: false
        description: Filter by holder name
        schema:
          type: string
      - name: direction
        in: query
        required: false
        description: 'Filter: increase, decrease, initial, ceased, change'
        schema:
          type: string
      - name: date_from
        in: query
        required: false
        description: Start date (YYYY-MM-DD)
        schema:
          type: string
      - name: date_to
        in: query
        required: false
        description: End date (YYYY-MM-DD)
        schema:
          type: string
      responses:
        '200':
          description: SPH Notices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /beneficial-ownership/{ticker}:
    get:
      operationId: getBeneficialOwnership
      summary: Beneficial Ownership
      description: Reconstructed beneficial ownership intelligence. Cross-references top-20 shareholder registers with ETF/fund holdings and custodian mappings to identify who is behind nominee/custodian entries. Returns direct holders, nominee breakdowns with identified fund managers, fund holdings summary, and substantial holders.
      tags:
      - Insider Trades
      x-tier: free
      parameters:
      - name: ticker
        in: path
        required: true
        description: NZX ticker symbol
        schema:
          type: string
      responses:
        '200':
          description: Beneficial Ownership
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /zapier/triggers/insider-trades:
    get:
      operationId: getZapierTriggersInsiderTrades
      summary: 'Zapier: New Insider Trade'
      description: Polling trigger for Zapier. Returns recent director share transactions sorted newest first. Includes director name, transaction type, shares, price, and total value.
      tags:
      - Insider Trades
      x-tier: free
      parameters:
      - name: ticker
        in: query
        required: false
        description: Comma-separated tickers
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: Transaction type (Purchase, Sale, Exercise)
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: 'Lookback days (default: 30, max: 90)'
        schema:
          type: number
      - name: limit
        in: query
        required: false
        description: 'Max results (default: 50, max: 100)'
        schema:
          type: number
      responses:
        '200':
          description: 'Zapier: New Insider Trade'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /quarterly-ownership-report:
    post:
      operationId: createQuarterlyOwnershipReport
      summary: Quarterly Ownership Report
      description: Generate a quarterly ownership PDF report for a portfolio of NZX companies. Top 20 shareholders, substantial holders, fund identification, HHI analysis.
      tags:
      - Insider Trades
      x-tier: enterprise
      responses:
        '200':
          description: Quarterly Ownership Report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /insider-correlation/{ticker}:
    get:
      operationId: getInsiderCorrelation
      summary: Insider-Announcement Correlation
      description: Insider trade and announcement tone correlation patterns for a company. Cross-references insider trading activity with announcement sentiment to surface patterns where insiders trade ahead of tone shifts.
      tags:
      - Insider Trades
      x-tier: free
      parameters:
      - name: ticker
        in: path
        required: true
        description: NZX ticker symbol (e.g., FPH, AIR, SPK)
        schema:
          type: string
      - name: months
        in: query
        required: false
        description: 'Lookback period in months (default: 12)'
        schema:
          type: integer
      - name: window_days
        in: query
        required: false
        description: 'Window in days around announcements to check for insider trades (default: 30)'
        schema:
          type: integer
      responses:
        '200':
          description: Insider-Announcement Correlation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          headers:
            $ref: '#/components/headers/RateLimitHeaders'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Missing API key
            message: Include your API key via X-API-Key header or ?api_key= query parameter.
            docs: https://nzxplorer.co.nz/developers
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Rate limit exceeded
            message: free tier allows 10 requests/minute.
            retry_after_seconds: 45
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Maximum requests allowed per minute
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Always 0 when rate limited
          schema:
            type: integer
  schemas:
    Envelope:
      type: object
      description: Standard API response envelope
      properties:
        data:
          description: Response payload
        meta:
          type: object
          properties:
            api_version:
              type: string
              example: v1
            timestamp:
              type: string
              format: date-time
            format:
              type: string
              enum:
              - standard
              - llm
              - fdc3
              - toon
            endpoint:
              type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        message:
          type: string
          description: Human-readable explanation
          nullable: true
        docs:
          type: string
          format: uri
          description: Link to API documentation
          nullable: true
        retry_after_seconds:
          type: integer
          description: Seconds to wait before retrying (rate limit only)
          nullable: true
      required:
      - error
  headers:
    RateLimitHeaders:
      X-RateLimit-Limit:
        description: Maximum requests allowed per minute
        schema:
          type: integer
      X-RateLimit-Remaining:
        description: Requests remaining in current window
        schema:
          type: integer
      X-RateLimit-Reset:
        description: Unix timestamp when the rate limit window resets
        schema:
          type: integer
      X-RateLimit-Limit-Day:
        description: Maximum requests allowed per day
        schema:
          type: integer
      X-RateLimit-Remaining-Day:
        description: Requests remaining for today
        schema:
          type: integer
      X-API-Tier:
        description: Authenticated API key tier (free, pro, enterprise, institutional)
        schema:
          type: string
      X-Request-ID:
        description: Unique request ID (UUID v4) for support correlation
        schema:
          type: string
          format: uuid
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key passed via the X-API-Key header
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as a query parameter