Reference

Page IDs and citations

How to turn an API response into a verifiable source link.

Every figure that has a filing-level source carries a page_id. Passing that id to /filings/{page_id}/snapshot returns a viewable URL -- a per-page PNG render of the original PDF, a SEC EDGAR link, or a link to the source document. A page_id has the form <document id>_<page>, for example 722df34e9f191a97518a8560755cb9e9_20 (Nordic) or 0000320193-25-000079_12 (US, prefixed by the SEC accession number).

This is the mechanism that lets you build audit-grade products: every number rendered to a user can hyperlink to the exact filing page that produced it.

Where page_ids appear

Endpoint	Field carrying page_id
`/filings/content-search`	`results[].page_id`, `sources[].page_id`
`/companies/{id}/statement`	`periods[].metrics.<key>.page_id` on Nordic figures extracted from a PDF page (`source: "avainluvut"`). ESEF figures link to the filing viewer via `source_url` instead. US statements carry no page ids; they are cited per annual filing in `periods[]._provenance`.
`/companies/{id}/financials`	Nordic: `by_year.<year>._provenance.page_ids` and `_provenance.metric_sources.<metric>.page_id`.
`/companies/compare`	Nordic: `_provenance.page_ids` in `latest_year` and each `by_year` entry.
`/companies/{id}/revenue-geography`	`countries[].page_id`, `regions[].page_id`, `other[].page_id`. On US rows this is the bare SEC accession number, which the snapshot endpoint cannot resolve.

Resolving a page_id

bash

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

The kind field distinguishes four snapshot types:

Kind	Description
`rendered_png`	Per-page PNG render of the original PDF filing.
`snapshot_endpoint`	Nordic filing page without a stored render: `snapshot_url` is Clarifo's snapshot endpoint, which renders the page on request.
`edgar_link`	SEC EDGAR link to the filing document for US filings.
`viewer_link`	Link to the source document (for example an ESEF viewer) for a Nordic filing that cannot be rendered per page.

Nordic filing with a render available

json

{
  "page_id": "722df34e9f191a97518a8560755cb9e9_20",
  "available": true,
  "kind": "rendered_png",
  "snapshot_url": "https://cdn.clarifo.com/snapshots/…/p20.png",
  "source_url": "https://…/api/pdf-snapshot?page_id=722df34e9f191a97518a8560755cb9e9_20",
  "company_name": "Neste Oyj",
  "year": "2024",
  "document_type": "annual_report",
  "page_number": 20,
  "source_kind": "s3_pdf",
  "page_number_kind": "pdf_render",
  "page_reference": "p. 20",
  "page_reference_type": "page",
  "dpi": 150,
  "citation_label": "Neste Oyj 2024, p. 20",
  "citation_markdown": "[Neste Oyj 2024, p. 20](https://cdn.clarifo.com/snapshots/…/p20.png)"
}

US filing -- SEC EDGAR link

json

{
  "page_id": "0000320193-25-000079_12",
  "available": true,
  "kind": "edgar_link",
  "snapshot_url": "https://www.sec.gov/Archives/edgar/data/…",
  "source_url": "https://www.sec.gov/Archives/edgar/data/…",
  "company_name": "Apple Inc.",
  "official_name": "Apple Inc.",
  "year": "2025",
  "document_type": "10-K",
  "page_number": 12,
  "section": "Item 7. Management's Discussion and Analysis",
  "source_kind": "sec_edgar",
  "page_reference": "Item 7. Management's Discussion and Analysis",
  "page_reference_type": "section",
  "citation_label": "Apple Inc. 2025 — Item 7. Management's Discussion and Analysis",
  "citation_markdown": "[Apple Inc. 2025 — Item 7. Management's Discussion and Analysis](https://www.sec.gov/Archives/edgar/data/…)"
}

Render not yet available

json

{
  "page_id": "722df34e9f191a97518a8560755cb9e9_20",
  "available": false,
  "company_name": "Neste Oyj",
  "year": "2024",
  "document_type": "annual_report",
  "page_number": 20,
  "source_kind": "s3_pdf",
  "reason": "Source page preview is not available for this filing yet",
  "page_reference": "p. 20",
  "page_reference_type": "page",
  "citation_label": "Neste Oyj 2024, p. 20",
  "citation_markdown": "Neste Oyj 2024, p. 20"
}

citation_label and citation_markdown are pre-formatted strings ready to embed directly in a UI or Markdown document. When available is false, citation_markdown has no link. See the snapshot endpoint for every reason value. Show users the citation fields, never the raw page_id.

Lifetime and caching

Nordic PNGs served via CDN are stable URLs. Safe to embed in your UI and cache.
Nordic PNGs served as S3 presigned URLs (no CDN) are valid for ~1 hour. Always resolve fresh before rendering.
EDGAR links are public and stable, but rate-limited by the SEC. Cache them aggressively.
Snapshot endpoint URLs (snapshot_endpoint) are stable Clarifo URLs keyed by page_id; the page is rendered when requested.
Viewer links are public and stable.

Use the kind field to decide caching policy -- never the URL itself.