api-ninjas-com Executive Compensation API

openapi: 3.2.0
info:
  title: Ninjas Executive Compensation API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Executive Compensation
  description: The Executive Compensation API returns the pay of named executive officers (CEO, CFO, and the next three highest-paid officers) for US public companies, sourced directly from SEC proxy statements (form DEF 14A). Each record includes salary, bonus, stock and option awards, non-equity incentive, pension and deferred compensation change, all other compensation, and total, plus the structured Pay Versus Performance disclosure (Compensation Actually Paid, total shareholder return, net income). The free tier returns the CEO's total for the latest fiscal year; premium plans unlock the full breakdown, all executives, historical years, and Pay Versus Performance.
paths:
  /v1/executivecompensation:
    get:
      summary: Get executive compensation for a US public company
      operationId: getExecutiveCompensation
      description: Returns named-executive-officer compensation for a company, sourced from SEC DEF 14A proxy statements, plus the structured Pay Versus Performance disclosure. The free tier returns the CEO's total for the latest fiscal year; premium tiers unlock the full breakdown, all executives, historical years, and Pay Versus Performance.
      parameters:
      - name: ticker
        in: query
        required: false
        description: The stock ticker of the company (e.g., AAPL). Either ticker or name is required. Share classes and preferred shares can be written in any common form, e.g. BRK.B, BRK-B, BRK/B or BRKB, and BAC.PRL or BAC-PL.
        schema:
          type: string
          example: AAPL
      - name: cik
        in: query
        required: false
        description: The company's SEC Central Index Key (CIK), with or without leading zeros (e.g., 320193 or 0000320193). An alternative to ticker.
        schema:
          type: string
          example: '320193'
      - name: name
        in: query
        required: false
        description: Company name to search for (e.g., apple), used when a ticker or cik is not provided.
        schema:
          type: string
      - name: year
        in: query
        required: false
        description: The 4-digit fiscal year to return. Each response covers a single year and defaults to the latest available year. Historical (non-latest) years require a paid (premium) plan; a year the company has no data for returns a no-data message.
        schema:
          type: integer
          example: 2024
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutiveCompensationResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      tags:
      - Executive Compensation
components:
  schemas:
    PayVersusPerformance:
      type: object
      description: Structured Item 402(v) Pay Versus Performance disclosure (fiscal years 2022 onward). Premium tiers only.
      properties:
        fiscal_year:
          type: integer
        ceo:
          type: string
          description: Name of the principal executive officer for the year.
        ceo_total_compensation:
          type: number
          description: CEO Summary Compensation Table total, in USD.
        ceo_compensation_actually_paid:
          type: number
          description: CEO Compensation Actually Paid (CAP), in USD. Can be negative.
        average_neo_total_compensation:
          type: number
          description: Average Summary Compensation Table total for the non-CEO named executive officers, in USD.
        average_neo_compensation_actually_paid:
          type: number
          description: Average Compensation Actually Paid for the non-CEO named executive officers, in USD.
        total_shareholder_return:
          type: number
          description: Company total shareholder return, indexed to a $100 initial investment.
        peer_group_total_shareholder_return:
          type: number
          description: Peer-group total shareholder return, indexed to a $100 initial investment.
        net_income:
          type: number
          description: Company net income in USD. Can be negative.
        company_selected_measure:
          type: object
          properties:
            name:
              type: string
              description: The company-selected financial performance measure.
            value:
              type: number
              description: The value of the company-selected measure for the year.
    Executive:
      type: object
      properties:
        name:
          type: string
          description: The executive's full name.
        position:
          type: string
          description: The executive's principal position/title as printed in the proxy (e.g., Chief Executive Officer).
        is_ceo:
          type: boolean
          description: True for the principal executive officer (CEO).
        fiscal_year:
          type: integer
          description: The fiscal year this compensation row covers.
        salary:
          type: number
          description: Salary in USD. Premium tiers only; returned as a premium-only message for free users.
        bonus:
          type: number
          description: Bonus in USD. Premium tiers only.
        stock_awards:
          type: number
          description: Grant-date fair value of stock awards in USD. Premium tiers only.
        option_awards:
          type: number
          description: Grant-date fair value of option awards in USD. Premium tiers only.
        non_equity_incentive:
          type: number
          description: Non-equity incentive plan compensation in USD. Premium tiers only.
        pension_and_deferred_compensation:
          type: number
          description: Change in pension value and nonqualified deferred compensation earnings in USD. Premium tiers only.
        all_other_compensation:
          type: number
          description: All other compensation in USD. Premium tiers only.
        total:
          type: number
          description: Total compensation in USD.
    ExecutiveCompensationResponse:
      type: object
      properties:
        ticker:
          type: string
          description: The company's stock ticker.
        company_name:
          type: string
          description: The company's name.
        cik:
          type: string
          description: The company's SEC Central Index Key (CIK).
        executives:
          type: array
          items:
            $ref: '#/components/schemas/Executive'
        pay_versus_performance:
          type: array
          items:
            $ref: '#/components/schemas/PayVersusPerformance'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api