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 an ESEF inline XBRL viewer link.

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`
`/companies/{id}/statement`	Available via content search on the returned metrics.
`/companies/{id}/revenue-geography`	`countries[].page_id`, `regions[].page_id`, `other[].page_id`

Resolving a page_id

bash

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

The kind field distinguishes three snapshot types:

Kind	Description
`rendered_png`	Per-page PNG render of the original PDF filing.
`edgar_link`	SEC EDGAR viewer link for US filings.
`viewer_link`	ESEF inline XBRL viewer link for Nordic filings.

Nordic filing with a render available

json

{
  "page_id": "722df34e9f191a97_20",
  "available": true,
  "kind": "rendered_png",
  "snapshot_url": "https://cdn.clarifo.com/snapshots/…/p20.png",
  "company_name": "Neste Oyj",
  "year": "2024",
  "document_type": "annual_report",
  "page_number": 20,
  "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",
  "available": true,
  "kind": "edgar_link",
  "snapshot_url": "https://www.sec.gov/Archives/edgar/data/…",
  "company_name": "Apple Inc.",
  "year": "2025",
  "document_type": "10-K",
  "citation_label": "Apple Inc. 10-K 2025",
  "citation_markdown": "[Apple Inc. 10-K 2025](https://www.sec.gov/Archives/edgar/data/…)"
}

Render not yet available

json

{
  "page_id": "abc",
  "available": false,
  "kind": null,
  "snapshot_url": null,
  "reason": "Page rendering pending"
}

citation_label and citation_markdown are pre-formatted strings ready to embed directly in a UI or Markdown document.

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.
Viewer links are public and stable.

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