Quickstart

1. Get a key

Sign in at clarifo.com → Settings → API keys → Create key (included in Pro, no application needed). Choose a live key for production or a test key (its own smaller cap inside your account quota) for development. The raw key is shown once. It looks like:

clf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Store it as an environment variable. Never commit it to source control.

export CLARIFO_API_KEY="clf_live_…"

2. Make your first call

Search for Neste's annual reports:

curl https://api.clarifo.com/api/v1/data/filings/search \
  -H "Authorization: Bearer $CLARIFO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company": "Neste", "document_type": "annual_report", "limit": 5}'

You should see a response like this (trimmed — real rows carry more fields, such as fiscal_year and citation_markdown):

{
  "filings": [
    {
      "docid": "3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b",
      "company_name": "Neste Oyj",
      "year": "2024",
      "document_type": "annual_report",
      "document_type_label": "Annual Report",
      "page_count": 142,
      "market": "nordic"
    }
  ],
  "total": 1
}

3. Pull structured financials

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

Returns annual revenue, operating income, EBITDA, net income, equity, cash flow, EPS — plus a latest_period block that surfaces the freshest quarterly figure when one is newer than the latest annual. Trimmed:

{
  "display_name": "Neste Oyj",
  "market": "nordic",
  "by_year": {
    "2024": {
      "revenue": 20640000000,
      "operating_income": 1850000000,
      "operating_margin": 9.0
    }
  },
  "latest_period": {
    "period_label": "Q3/2025",
    "period_type": "quarterly",
    "period_end": "2025-09-30",
    "metrics": {
      "revenue": {"value": 5800000000, "unit": "EUR"}
    }
  }
}

Amounts are in the reporting currency's base unit (here EUR, not millions); margins are percentages, so 9.0 means 9.0 %. See Markets and currencies.

Before using a body as data, check it for an error field: a company with nothing on file comes back as HTTP 200 with error and failure_kind (see Errors).

4. Cite your numbers

Figures with a filing-level source come with a page_id. For Nordic filings it is a 32-character hex document id, an underscore and a page number. Resolve it to a viewable URL:

curl https://api.clarifo.com/api/v1/data/filings/3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b_87/snapshot \
  -H "Authorization: Bearer $CLARIFO_API_KEY"

Nordic filings return a per-page PNG (CloudFront-cached) or, where no render exists, an ESEF viewer link. US filings return a SEC EDGAR link. Either way, your end users can click straight to the exact page that produced the number. A page that cannot be resolved comes back as HTTP 200 with "available": false and a reason.

Next steps

• Authentication — bearer header, lifecycle.
• Errors — every status code you may see, and tool-level misses.
• Rate limits — per-second, per-minute, and monthly quotas.