API · Companies

Compare companies

Side-by-side KPIs for 2–5 issuers, Nordic + US can be mixed.

POST/api/v1/data/companies/compare

Fetches financials for each company in the input list and returns a structured comparison object. Nordic and US issuers can be mixed in a single call (e.g. "Neste vs ExxonMobil").

When to use this

A peer table on a company page.
Cross-market comparison ("how does the Helsinki gas peer compare to ExxonMobil?").
One-click answer to "who is winning?" for a small competitive set.

Body

Field	Type	Description
companiesrequired	string[]	2–5 names or tickers.
years	integer default: 3	Recent years per company (1–10).

Example

bash

curl https://api.clarifo.com/api/v1/data/companies/compare \
  -H "Authorization: Bearer $CLARIFO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": ["Neste", "ExxonMobil"],
    "years": 3
  }'

Response

json

{
  "companies": [
    {
      "company_name": "Neste Oyj",
      "display_name": "Neste Oyj",
      "market": "nordic",
      "latest_year": {"year": "2024", "revenue": 21990000000, "net_income": 640000000},
      "by_year": {"2024": { … }, "2023": { … }}
    },
    {
      "company_name": "Exxon Mobil Corp",
      "display_name": "Exxon Mobil Corp",
      "market": "us",
      "ticker": "XOM",
      "latest_year": { … },
      "by_year": { … }
    }
  ],
  "kpis": ["revenue", "gross_profit", "operating_income", "net_income"],
  "not_found": []
}

Output shape

companies — one entry per resolved issuer with latest_year (a flat dict of KPIs) and by_year (the full series).
kpis — the list of metric keys that appear in latest_year. Use it to drive table column headers.
not_found — input strings the resolver could not map. Surface these to the user instead of silently dropping them.

Limits

2 to 5 companies per call.
1 to 10 historical years per company.