API · Companies

Screen the company universe

Rank companies by growth or absolute value of a metric, with filters.

POST/api/v1/data/companies/screen

Ranks the entire Clarifo universe by a financial metric, optionally filtered by country, industry, or tag taxonomy. Designed for cross-company questions:

"Which Finnish companies grew revenue most in 2024?"
"Top 20 Swedish companies by EBITDA."
"Which construction-sector companies had the largest order book?"

Body

Field	Type	Description
metric	string default: revenue	Metric key — see coverage below.
mode	string default: growth	growth \| value.
year	integer	Anchor year. Default: latest available.
compare_years	integer default: 1	Growth mode only: how many years back (1 = YoY, 4 = 4-year CAGR).
country	string	FI \| SE \| Nordic \| US. Nordic screens Helsinki and Stockholm in one pass. Omit to scan both markets. Other values (e.g. DK) are rejected.
industry	string	Free-text substring on companies.industry.
tag_slugs	string[]	Precise sector / theme filter via the company_tags taxonomy.
top_n	integer default: 20	1–100.
direction	string default: desc	desc \| asc.
min_value	number	Drop micro-caps from a value ranking. Compared in native currency, so combine with country.

Example

bash

curl https://api.clarifo.com/api/v1/data/companies/screen \
  -H "Authorization: Bearer $CLARIFO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "revenue",
    "mode": "growth",
    "year": 2024,
    "country": "FI",
    "top_n": 20
  }'

Response

json

{
  "metric": "revenue",
  "mode": "growth",
  "year": 2024,
  "compare_year": 2023,
  "filters": {"country": "FI"},
  "companies": [
    {
      "company_name": "fiskars",
      "display_name": "Fiskars Oyj Abp",
      "ticker": "FSKRS.HE",
      "country": "FI",
      "industry": "Consumer Goods",
      "entity_type": "operating",
      "market": "nordic",
      "currency": "EUR",
      "value_anchor": 1320.0,
      "value_compare": 1250.0,
      "growth_pct": 5.6,
      "delta_absolute": 70.0,
      "trend": "growing",
      "signs_consistent": true,
      "value_anchor_eur": 1320.0,
      "value_compare_eur": 1250.0
    }
  ],
  "coverage": {
    "total_in_scope": 120,
    "with_data": 47,
    "returned": 20
  }
}

Empty fields are omitted rather than sent as null, so coverage_warning, excluded_data_quality and unset filters keys only appear when they apply.

Invalid input is returned as HTTP 200 with an error body, for example:

json

{
  "error": "country must be one of FI, SE, US, NORDIC or None; got 'DK'",
  "failure_kind": "invocation_error"
}

Company fields

Field	Description
`entity_type`	`"operating"`, `"holding"`, `"reit"`, `"bank"`, etc.
`value_anchor` / `value_compare`	Metric value at the anchor year and the comparison year.
`growth_pct`	Growth percentage from the compare year to the anchor year. Omitted when either value is negative (e.g. a loss); use `trend` and `delta_absolute` then.
`delta_absolute`	Absolute change (`value_anchor - value_compare`).
`trend`	`"growing"`, `"declining"` or `"flat"` for two non-negative values; `"turned_positive"` / `"turned_negative"` when the sign flipped; `"improving"` / `"deteriorating"` when both are negative.
`signs_consistent`	`true` when both values are non-negative; `false` when either is negative.
`value_anchor_eur` / `value_compare_eur`	Approximate EUR values, converted at fixed rough annual-average rates. Good for ranking across currencies, not for accounting. Only meaningful for currency amounts; for margins and ratios use `value_anchor`. Value-mode screens of currency amounts rank on these.

Coverage

The coverage object reports how broadly the screen matched:

Field	Description
`total_in_scope`	Companies matching the filters (before checking metric data).
`with_data`	Companies with data for the requested metric and year.
`returned`	Companies returned (capped by `top_n`).

coverage_warning is present (a string) when fewer than 20 % of in-scope companies reported the metric.

Data-quality exclusions

In growth mode, a company whose anchor and compare figures cannot be on the same scale (a swing of 100x or more on a currency amount, or a change of reporting currency between the two years) is withheld from the ranking. It is listed under excluded_data_quality, each row with its own data_quality_warnings, and the response carries a top-level data_quality_warning string. Such a figure is an extraction error, not a result. Margins and ratios are exempt from this check.

Metric coverage

The screener picks the right backend automatically based on the metric key.

Pre-aggregated Nordic metrics (fastest): revenue, gross_profit, ebit, ebitda, net_income, operating_cash_flow, free_cash_flow, marketcap, personnel, eps_diluted, shares_outstanding.
Granular IFRS line items (Nordic ESEF facts): cost_of_sales, operating_profit, profit_before_tax, income_tax_expense, research_and_development_expense, selling_and_marketing_expense, administrative_expense, finance_costs, finance_income, total_assets, current_assets, non_current_assets, total_equity, equity_attributable_to_owners, total_liabilities, current_liabilities, non_current_liabilities, cash_and_equivalents, investing_cash_flow, financing_cash_flow.
Filing-extracted KPIs (Nordic): order_book, order_intake, equity_ratio, …
Derived margins (Nordic + US): gross_margin, operating_margin, ebit_margin, ebitda_margin, net_margin, net_profit_margin, fcf_margin. Computed from the numerator and revenue. Returned as ratios (0.25 = 25 %), unlike the percentages in compare.
Derived returns (Nordic ESEF): roe / return_on_equity, roa / return_on_assets, as ratios.
US (US-GAAP tags): the granular line items above, plus revenue, gross_profit, ebit, net_income, operating_cash_flow, eps_diluted, shares_outstanding and the derived margins. ebitda and ebitda_margin are derived as operating income plus depreciation and amortization; fcf_margin as (operating cash flow − capex) / revenue. Companies that did not file the D&A or capex line are left out of those rankings rather than treated as zero. Not available for US: free_cash_flow, marketcap, personnel, order_book, order_intake, equity_ratio, roe, roa.

The same metric key always means the same concept across markets.