Get key financial figures

Returns a compact KPI summary for a company: annual revenue, gross profit, operating income, EBIT, EBITDA, net income, EPS, total assets, equity, equity ratio, operating + free cash flow, and per-period margins. The response also includes a latest_period block that surfaces the freshest disclosure — annual or quarterly, whichever ended most recently. With period_type=quarterly it also returns a by_quarter series for Nordic and US companies, so you can chart quarters directly.

When to use this

• Headline KPIs on a company card.
• Driving a "latest revenue" tile that updates the moment a Q3 release lands.
• Quarterly revenue or earnings charts (period_type=quarterly).
• Smoke-testing whether Clarifo has any data for a given ticker.

For line-item detail, use the statement endpoint.

Example

curl "https://api.clarifo.com/api/v1/data/companies/Neste/financials?years=5" \
  -H "Authorization: Bearer $CLARIFO_API_KEY"

Response

{
  "company_name": "Neste",
  "display_name": "Neste Oyj",
  "market": "nordic",
  "by_year": {
    "2024": {
      "revenue": 21990000000,
      "gross_profit": 3200000000,
      "operating_income": 1850000000,
      "EBIT": 1850000000,
      "EBITDA": 2400000000,
      "net_income": 640000000,
      "eps_diluted": 0.83,
      "total_assets": 18500000000,
      "total_equity": 9200000000,
      "current_assets": 7100000000,
      "non_current_assets": 11400000000,
      "operating_cash_flow": 2100000000,
      "capital_expenditures": 800000000,
      "free_cash_flow": 1300000000,
      "revenue_growth": -2.1,
      "ebitda_margin": 10.9,
      "operating_margin": 8.4,
      "net_profit_margin": 2.9,
      "equity_ratio": 49.7,
      "_provenance": {
        "primary_source": "nordic_avainluvut+keymetrics",
        "page_ids": ["3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b_87"],
        "metric_sources": {"revenue": {"page_id": "3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b_87"}}
      }
    },
    "2023": { "revenue": 22458000000, "…": "…" }
  },
  "latest_period": {
    "period_label": "Q3/2025",
    "period_type": "quarterly",
    "year": 2025,
    "quarter": 3,
    "period_start": "2025-07-01",
    "period_end": "2025-09-30",
    "source": "eu_avainluvut_q",
    "metrics": {
      "revenue": {"value": 5800000000, "unit": "EUR", "source": "eu_avainluvut_q"}
    }
  }
}

company_name echoes the identifier you sent for Nordic companies; use display_name for the canonical name. ticker and exchange are returned for US companies only. Empty fields are omitted rather than sent as null — data_quality_warnings, for example, only appears when a warning was raised.

Each latest_period.metrics entry carries its own unit. Unlike by_year, margins and ratios there are fractions with "unit": "ratio" (0.084 = 8.4 %), so check unit before formatting.

by_year fields

Each year object contains up to 20 typed core metrics. Additional market-specific metrics may appear as extra keys.

Money amounts are in the reporting currency's base unit (EUR, SEK, USD, not thousands or millions). Margins and ratios are percentages: "operating_margin": 8.4 means 8.4 %, not 0.084.

A metric that is not available for a year is omitted from that year's object. US by_year objects carry the XBRL-tagged figures (revenue, gross profit, operating income, net income, EPS, assets, equity, cash flow, capex) plus a derived lowercase ebit / ebitda; margins and ratios are not included for US companies — compute them from the amounts, or use compare, which does.

Provenance

Each year object may carry a _provenance block:

• Nordic: page_ids (every filing page the year's figures came from) and metric_sources ({metric: {page_id}} for the cell that supplied each figure). Resolve any page_id with the snapshot endpoint. Values from market data feeds have no page anchor.
• US: period_end, a filing block (form_type, accession_number, filing_date, document_url, ...) and metric_sources ({metric: {tag, accession_number, form_type, period_end, unit, document_url}}) naming the XBRL tag and 10-K (or 10-K/A) behind each figure.

by_quarter

period_type=quarterly adds a by_quarter object keyed by fiscal quarter ("Q2/2027"), newest first, plus a quarterly_coverage summary (complete = quarters with revenue, operating income and net income; partial, total, and for US derived). It is omitted when no quarterly figures exist. Nordic and US quarters share one shape and the metric keys of by_year; money amounts are in the reporting currency's base unit.

"by_quarter": {
  "Q2/2027": {
    "year": 2027,
    "quarter": 2,
    "period_start": "2026-04-27",
    "period_end": "2026-07-26",
    "derived": true,
    "metrics": {
      "revenue": {
        "value": 96221000000,
        "unit": "USD",
        "status": "reported_standalone",
        "derived": false,
        "tag": "Revenues",
        "form_type": "10-Q",
        "accession_number": "0001045810-26-000075",
        "period_start": "2026-04-27",
        "period_end": "2026-07-26"
      },
      "operating_cash_flow": {
        "value": 24077000000,
        "unit": "USD",
        "status": "derived_subtraction",
        "derived": true,
        "formula": "q2 = 6m - q1",
        "form_type": "10-Q",
        "accession_number": "0001045810-26-000075",
        "source_accessions": ["0001045810-26-000075", "0001045810-26-000052"]
      }
    },
    "source": {
      "form_type": "10-Q",
      "accession_number": "0001045810-26-000075",
      "period_end": "2026-07-26",
      "document_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000075/0001045810-26-000075-index.htm"
    }
  }
}

year and quarter are the company's own fiscal numbering, not the calendar quarter: NVIDIA's quarter ended 2026-07-26 is fiscal Q2 2027. Check period_end for the calendar dates.

US quarters come from the 10-Q and 10-K XBRL filings:

• Only three-month figures are served as a quarter. A 10-Q also tags year-to-date totals (six and nine months); these are never returned as a quarter value.
• Where a 10-Q reports a figure only year-to-date (usually cash flow), the quarter is computed as the difference of two year-to-date totals from the same fiscal year (q2 = 6m - q1, q3 = 9m - 6m) and flagged.
• There is no 10-Q for the fourth quarter. Q4 is FY - (Q1 + Q2 + Q3), computed only when the 10-K annual figure and all three quarters exist under the same XBRL tag; otherwise that metric is left out of Q4. Balance-sheet values (total_assets, total_equity) for Q4 are the 10-K year-end figures. eps_diluted is never computed, so a US Q4 has no EPS.
• Any computed value has "derived": true, "status": "derived_subtraction", a formula and source_accessions (every filing it was computed from). A bucket's own derived is true when any of its metrics is derived.
• Each value names the form_type, accession_number, XBRL tag and period_end it came from. source names the filing that reported the quarter (the 10-K for Q4), with an EDGAR document_url.
• US metric keys: revenue, gross_profit, operating_income, net_income, eps_diluted, total_assets, total_equity, operating_cash_flow, capital_expenditures.

Nordic quarters come from the validated interim-report facts. Each value carries status (reported_standalone, derived_subtraction, derived_ratio, manual), formula for derived values, confidence, validated_against_fy and source_page_ids (resolve them with the snapshot endpoint).

Period selection rules

For US companies with period_type=quarterly, latest_period is the newest by_quarter entry ("source": "us_xbrl_quarterly", with its filing) whenever that quarter ends later than the period otherwise selected, or when that period is not a quarter. The period it replaced is named under latest_period.superseded_period. A derived Q4 keeps its derived and formula fields there too.

When year or quarter is pinned and no structured data exists for that period, latest_period is not substituted with a different one. It comes back as:

{
  "available": false,
  "reason": "requested_period_not_available",
  "requested": {"year": 2026, "quarter": 2, "period_type": "quarterly"},
  "explanation": "No structured financial data found for the requested period Q2/2026. …",
  "nearest_available": {"period_label": "Q1/2026", "…": "…"}
}

A resolved period with no ingested metrics carries "metrics_available": false; on an unpinned request the response then falls back to the newest period that has figures and records the skipped one under latest_period.superseded_period.

Coverage gaps and misses

If the company resolves but its statement tables are empty, the response is HTTP 200 with "available": false, "reason": "no_detailed_data" and an explanation, instead of by_year.

If the company cannot be found in either market, the response is HTTP 200 with an error body:

{
  "error": "Company not found",
  "failure_kind": "not_found",
  "company": "Acme Widgets",
  "tried_markets": ["nordic", "us"]
}

When the company exists in the filing index but has no structured figures yet, error is "Financial data not available" and a filing_index block names the resolved company. Miss responses may also include a suggestions list of follow-up calls.