Pricing Blog Insights Playground
Dashboard

Retirement Plans

GET/api/footnotes/retirement-plans

Pro

Returns defined-benefit pension and other-postretirement (OPEB) disclosures from the benefits footnote: funded status, benefit obligation, cost components, employer contributions, discount-rate assumptions, and the plan-asset book with asset categories cross-tabbed by fair-value level (Level 1 / 2 / 3 / NAV).

Each period entry carries one object per plan bucket, the (type, location) grid the filer disclosed: pension vs postretirement vs supplemental, US vs foreign vs a specific country. Buckets the filer left untagged appear with type/location null (the all-plans rollup). Raw axis members ride along in typeMembers/locationMembers; the plan-asset book nests under planAssets.byCategory with per-level amounts plus actual and target allocation shares.

fundedStatus is the filer's tagged figure when present; otherwise it is derived as planAssets.total − benefitObligation (same bucket, one currency) and flagged fundedStatusDerived: true.

Monetary values default to US dollars (currency parameter as on the statements endpoints: balances at the period-end spot rate, cost/contribution flows at the period-average rate, fx audit block, currency=original for as-filed). Rates and allocation shares are fractions of 1 and never converted.

What this data can tell you:

Data honesty notes:

Get API key Try it live in the API explorer

Query parameters

Example request

curl 'https://api.stockfit.io/v1/api/footnotes/retirement-plans?symbol=AAPL&cik=320193&cusip=037833100&composite_figi=BBG000B9XRY4&share_class_figi=BBG001S5N8V8&currency=USD' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Responses

200 OK

Defined-benefit plan disclosures by (type, location) bucket, organized by period

Response schema

array of:
  • period string (date)

    The fiscal period end date (YYYY-MM-DD)

  • fiscalYear integer

    The company's fiscal year (handles non-December year-ends).

  • fiscalPeriod string (enum)

    Fiscal period of a reported value: `FY` (annual) or `Q1`-`Q4` (quarterly).

    Allowed values: FY, Q1, Q2, Q3, Q4
  • plans array of object

    One entry per disclosed (type, location) bucket, sorted by benefit obligation descending. Fields the filer did not tag are omitted.

    array of:
    • type string (enum) | null

      Plan-type category derived from the plan-type axis member; null when untagged (the all-plans rollup).

      Allowed values: pension, postretirement, supplemental, other, null
    • location string | null

      `US`, `foreign`, a specific ISO 3166-1 country code (`GB`, `JP`) when the filer tagged one, `other`, or null when untagged.

    • typeMembers array of string

      Raw plan-type axis member QNames observed in this bucket.

    • locationMembers array of string
    • currency string | null

      Currency of the plan-level monetary values after conversion; null when mixed (see `fx.unconverted`)

    • normalized boolean

      Only present (as `true`) when a rate or allocation was re-scaled from a mis-tagged whole percent.

    • benefitObligation number

      Projected/accumulated benefit obligation at period end

    • fundedStatus number

      Plan assets minus obligation. Tagged by the filer when available; otherwise derived (see `fundedStatusDerived`).

    • fundedStatusDerived boolean

      Only present (as `true`) when `fundedStatus` was computed as planAssets.total − benefitObligation rather than tagged.

    • employerContributions number

      Employer contributions during the period (flow)

    • netPeriodicCost number

      Net periodic benefit cost for the period (flow)

    • actualReturn number

      Actual return on plan assets for the period (flow)

    • planAssets object

      The plan-asset book.

      • total number

        Fair value of plan assets at period end (bucket total)

      • byCategory array of object

        Asset categories cross-tabbed by fair-value level, sorted by size.

        array of:
        • member string

          Raw XBRL member QName of the asset category

        • name string

          Derived display label

        • currency string | null
        • normalized boolean
        • total number

          Category total (tagged without a level)

        • level1 number

          Level 1 (quoted prices)

        • level2 number

          Level 2 (observable inputs)

        • level3 number

          Level 3 (unobservable inputs)

        • nav number

          Measured at net asset value as a practical expedient

        • allocation number

          Actual weighted-average allocation share of this category (fraction of 1)

        • targetAllocation number

          Target allocation share (fraction of 1)

    • cost object

      Net-periodic-cost components (flows).

      • service number

        Service cost

      • interest number

        Interest cost

      • expectedReturn number

        Expected return on plan assets (income component, usually positive as filed)

      • lossAmortization number

        Amortization of actuarial gains/losses

      • priorServiceAmortization number

        Amortization of prior service cost/credit

    • assumptions object

      Weighted-average assumptions as fractions of 1.

      • discountRateBenefitObligation number

        Discount rate used for the benefit obligation

      • discountRateNetPeriodicCost number

        Discount rate used for net periodic cost

      • expectedReturnRate number

        Expected long-term return on plan assets

  • dateFiled string (date) | null

    SEC filing acceptance date of the newest filing contributing to this period. Use this to gate point-in-time data and avoid lookahead bias.

  • fx object

    Foreign-currency conversion audit for this period. Every monetary value in `facts` is in the requested `currency` (default **US dollars**). This block is absent when the period was already wholly in the target currency (e.g. a US filer with the default USD, nothing to convert). It is present when one or more line items were originally filed in a different currency and converted on the fly, and it records the exact rate(s) applied so the conversion can be reproduced. Rates come from the Frankfurter API (api.frankfurter.dev). Instant balance-sheet items use the spot rate at period end; flow income/cash-flow items use the day-weighted average rate over the period.

    • targetCurrency string

      The currency (ISO 4217) every `facts` value was converted INTO, the value of the request `currency` parameter (default USD). The literal `original` here means no conversion was requested: each fact stays in its as-reported currency (see `unconverted` for the per-fact mapping).

    • originalCurrencies array of string

      Every source currency (ISO 4217) that appeared in this period, the union of converted, unconverted, and already-in-target. The target currency itself is listed when some facts were natively in it (e.g. a foreign filer reporting some lines in USD alongside its converted local currency), so a mixed period reflects its true composition rather than appearing wholly converted.

    • rates array of object

      One entry per (source currency, method) actually applied. `rate` is the multiplier: `target = original * rate`.

      array of:
      • from string

        ISO 4217 source currency that was converted.

      • method string (enum)

        `spot` for instant balance-sheet items (rate at period end); `average` for flow income/cash-flow items (day-weighted mean over the period).

        Allowed values: spot, average
      • rate number

        Multiply the original-currency amount by this to get the `targetCurrency` amount.

      • effectiveDate string (date)

        Spot only: the date (YYYY-MM-DD) the applied rate was published (≤ period end).

      • start string (date)

        Average only: period start (YYYY-MM-DD).

      • end string (date)

        Average only: period end (YYYY-MM-DD).

    • unconverted map of string to array of string

      Facts that could NOT be converted (no published rate within tolerance, or an unsupported code/date), grouped by the currency they remain in: each key is a source ISO 4217 code, each value lists the curated fact names in `facts` still in that currency (NOT `targetCurrency`). Absent when everything converted. Use it to know exactly which figures to treat as native currency.

      • * (additional properties) array of string

Example response

[
  {
    "period": "2025-12-31",
    "fiscalYear": 2025,
    "fiscalPeriod": {},
    "plans": [
      {
        "type": "pension",
        "location": "US",
        "typeMembers": [
          "us-gaap:PensionPlansDefinedBenefitMember"
        ],
        "locationMembers": [
          "country:US"
        ],
        "currency": "USD",
        "normalized": true,
        "benefitObligation": 48472000000,
        "fundedStatus": -1737000000,
        "fundedStatusDerived": true,
        "employerContributions": 1159000000,
        "netPeriodicCost": 830000000,
        "actualReturn": 0,
        "planAssets": {
          "total": 46735000000,
          "byCategory": [
            {
              "member": "us-gaap:DefinedBenefitPlanEquitySecuritiesMember",
              "name": "Defined Benefit Plan Equity Securities",
              "currency": "USD",
              "normalized": true,
              "total": 0,
              "level1": 0,
              "level2": 1386000000,
              "level3": 0,
              "nav": 0,
              "allocation": 0.35,
              "targetAllocation": 0.4
            }
          ]
        },
        "cost": {
          "service": 0,
          "interest": 0,
          "expectedReturn": 0,
          "lossAmortization": 0,
          "priorServiceAmortization": 0
        },
        "assumptions": {
          "discountRateBenefitObligation": 0.056,
          "discountRateNetPeriodicCost": 0.052,
          "expectedReturnRate": 0.068
        }
      }
    ],
    "dateFiled": "2026-02-18",
    "fx": {}
  }
]

400 Bad Request

Invalid parameters or symbol not found

Response schema

  • error string

    Human-readable error message

Example response

{}

403 Forbidden

Feature not available on current plan

Response schema

  • error string

    Human-readable error message

Example response

{}