Screenshot API for Healthcare Platforms: Compliance Documentation and Formulary Monitoring

Healthcare has the most constrained screenshot automation environment of any industry: HIPAA creates hard limits on what can be captured, and CMS regulations create hard requirements on what must be documented. Screenshot APIs in healthcare operate at the intersection of those two constraints.

This post covers the patterns that work within those constraints: public-facing compliance documentation, formulary and benefit change monitoring, consent flow capture, and regulatory notice archiving. All examples capture only public or de-identified pages — never PHI.

The Healthcare Screenshot Constraint Set

Before the code, the constraint map:

What you cannot capture: - Any page displaying protected health information (PHI) — patient records, claims, clinical notes - Authenticated patient portal views (screenshots of these would be PHI by definition) - Any session authenticated as a specific patient

What you can and should capture: - Public-facing plan comparison and formulary pages - CMS and payer compliance notice pages (publicly accessible) - Consent and disclosure flows shown to patients before authentication - Your own public-facing enrollment, pricing, and benefit pages - Competitor payer or formulary pages (public information)

This boundary — public-facing only — is the defining constraint of healthcare screenshot automation. Everything else follows the same patterns as legal tech or fintech, but with this constraint as a first principle.

Formulary Change Monitoring

Drug formularies change quarterly (and sometimes mid-year). When a plan's formulary changes, providers, pharmacies, and patients need to know. Monitoring the public formulary pages of payers and PBMs gives advance notice:

import requests
import hashlib
import sqlite3
import json
from datetime import datetime, timezone
from pathlib import Path

SCREENSHOT_API = "https://hermesforge.dev/api/screenshot"
API_KEY = "your_api_key_here"

class FormularyMonitor:
    def __init__(self, db_path: str = "formulary_monitor.db",
                 screenshot_dir: str = "formulary_screenshots"):
        self.screenshot_dir = Path(screenshot_dir)
        self.screenshot_dir.mkdir(exist_ok=True)
        self.db_path = db_path
        self._init_db()

    def _init_db(self):
        with sqlite3.connect(self.db_path) as conn:
            conn.execute("""
                CREATE TABLE IF NOT EXISTS formulary_pages (
                    id TEXT PRIMARY KEY,
                    payer_name TEXT,
                    plan_name TEXT,
                    url TEXT,
                    tier TEXT,
                    check_interval_hours INTEGER DEFAULT 24,
                    last_checked TEXT,
                    last_hash TEXT,
                    change_count INTEGER DEFAULT 0
                )
            """)
            conn.execute("""
                CREATE TABLE IF NOT EXISTS formulary_snapshots (
                    id INTEGER PRIMARY KEY AUTOINCREMENT,
                    page_id TEXT,
                    captured_at TEXT,
                    file_path TEXT,
                    image_hash TEXT,
                    change_detected BOOLEAN DEFAULT 0,
                    change_significance TEXT
                )
            """)

    def add_formulary_page(self, page_id: str, payer_name: str,
                            plan_name: str, url: str,
                            tier: str = "commercial",
                            check_interval_hours: int = 24):
        """Register a public formulary page for monitoring."""
        with sqlite3.connect(self.db_path) as conn:
            conn.execute("""
                INSERT OR IGNORE INTO formulary_pages
                (id, payer_name, plan_name, url, tier, check_interval_hours)
                VALUES (?, ?, ?, ?, ?, ?)
            """, (page_id, payer_name, plan_name, url, tier, check_interval_hours))

    def check_formulary(self, page_id: str) -> dict:
        """Check a formulary page for changes. Captures unmodified public page."""
        with sqlite3.connect(self.db_path) as conn:
            row = conn.execute(
                "SELECT url, last_hash, payer_name, plan_name FROM formulary_pages WHERE id = ?",
                (page_id,)
            ).fetchone()

        if not row:
            return {"error": f"unknown page_id: {page_id}"}

        url, prev_hash, payer_name, plan_name = row

        # Formulary pages: no modifications — capture public page as-is
        # Do not block ads (payer pages may use ad networks for analytics)
        # Do not inject CSS (avoid altering what's displayed)
        resp = requests.get(SCREENSHOT_API, params={
            "url": url,
            "width": 1440,
            "full_page": True,
            "wait_for": "networkidle",
            "format": "png"  # Lossless for compliance records
        }, headers={"X-API-Key": API_KEY})

        if resp.status_code != 200:
            return {"page_id": page_id, "error": f"HTTP {resp.status_code}"}

        image_bytes = resp.content
        image_hash = hashlib.sha256(image_bytes).hexdigest()
        timestamp = datetime.now(timezone.utc).isoformat()
        change_detected = prev_hash is not None and prev_hash != image_hash

        filename = f"{page_id}_{timestamp.replace(':', '-')}.png"
        file_path = self.screenshot_dir / filename
        file_path.write_bytes(image_bytes)

        with sqlite3.connect(self.db_path) as conn:
            conn.execute("""
                INSERT INTO formulary_snapshots
                (page_id, captured_at, file_path, image_hash, change_detected)
                VALUES (?, ?, ?, ?, ?)
            """, (page_id, timestamp, str(file_path), image_hash, change_detected))

            conn.execute("""
                UPDATE formulary_pages SET last_checked = ?, last_hash = ?,
                    change_count = change_count + ? WHERE id = ?
            """, (timestamp, image_hash, 1 if change_detected else 0, page_id))

        return {
            "page_id": page_id,
            "payer": payer_name,
            "plan": plan_name,
            "change_detected": change_detected,
            "file": str(file_path),
            "hash": image_hash
        }

    def run_daily_check(self) -> list[dict]:
        with sqlite3.connect(self.db_path) as conn:
            page_ids = [r[0] for r in conn.execute("SELECT id FROM formulary_pages").fetchall()]
        return [self.check_formulary(pid) for pid in page_ids]

    def get_changed_pages(self) -> list[dict]:
        return [r for r in self.run_daily_check() if r.get("change_detected")]

Consent Flow Documentation

Healthcare platforms must document their patient consent flows — the screens patients see before providing consent to treatment, data sharing, or enrollment. This is the same pattern as SaaS cancellation flow documentation, applied to a higher-stakes context:

def capture_consent_flow(base_url: str, consent_steps: list[str],
                          flow_name: str, version_tag: str,
                          output_dir: str = "consent_docs") -> dict:
    """
    Capture each step of a consent flow for compliance documentation.

    Captures public-facing or pre-authentication consent pages only.
    These are the screens shown BEFORE a patient logs in.

    flow_name: e.g. "hipaa_authorization", "treatment_consent", "data_sharing"
    version_tag: app version or release tag
    """
    output_path = Path(output_dir) / flow_name / version_tag
    output_path.mkdir(parents=True, exist_ok=True)

    captures = []
    for i, step_url in enumerate(consent_steps, 1):
        # Consent pages: lossless PNG, no modifications
        resp = requests.get(SCREENSHOT_API, params={
            "url": step_url,
            "width": 1440,
            "full_page": True,
            "wait_for": "networkidle",
            "format": "png"
            # No block_ads, no inject_css — consent pages must appear as patients see them
        }, headers={"X-API-Key": API_KEY})

        if resp.status_code != 200:
            captures.append({"step": i, "url": step_url, "status": "error",
                             "http_status": resp.status_code})
            continue

        image_bytes = resp.content
        step_name = step_url.rstrip("/").split("/")[-1] or f"step_{i}"
        filename = f"step_{i:02d}_{step_name}.png"
        file_path = output_path / filename
        file_path.write_bytes(image_bytes)

        captures.append({
            "step": i,
            "url": step_url,
            "status": "ok",
            "file": str(file_path),
            "sha256": hashlib.sha256(image_bytes).hexdigest(),
            "captured_at": datetime.now(timezone.utc).isoformat()
        })

    manifest = {
        "flow_name": flow_name,
        "version": version_tag,
        "captured_at": datetime.now(timezone.utc).isoformat(),
        "total_steps": len(consent_steps),
        "successful": sum(1 for c in captures if c["status"] == "ok"),
        "steps": captures
    }

    with open(output_path / "manifest.json", "w") as f:
        json.dump(manifest, f, indent=2)

    return manifest

CMS Compliance Notice Archiving

CMS (Centers for Medicare & Medicaid Services) publishes regulatory notices, coverage determinations, and compliance guidance on public-facing portals. Health plans, TPAs, and healthcare technology vendors monitor these for material changes:

import hmac

class CMSNoticeArchive:
    def __init__(self, archive_dir: str, secret_key: bytes):
        """
        HMAC-chained archive of CMS regulatory notices.

        Treats regulatory notice changes the same as legal evidence —
        they may be referenced in compliance reviews or audits.
        """
        self.archive_dir = Path(archive_dir)
        self.archive_dir.mkdir(parents=True, exist_ok=True)
        self.secret_key = secret_key
        self.manifest_path = self.archive_dir / "notice_chain.jsonl"

    def capture_notice(self, notice_id: str, url: str,
                       category: str = "coverage_determination",
                       description: str = None) -> dict:
        """
        Capture a CMS notice page and add to HMAC chain.
        Only captures public CMS pages — never authenticated portals.
        """
        timestamp = datetime.now(timezone.utc).isoformat()

        resp = requests.get(SCREENSHOT_API, params={
            "url": url,
            "width": 1440,
            "full_page": True,
            "wait_for": "networkidle",
            "format": "png"
            # No modifications — regulatory evidence
        }, headers={"X-API-Key": API_KEY})
        resp.raise_for_status()

        image_bytes = resp.content
        image_hash = hashlib.sha256(image_bytes).hexdigest()

        filename = f"{notice_id}_{timestamp.replace(':', '-')}.png"
        file_path = self.archive_dir / filename
        file_path.write_bytes(image_bytes)

        entry = {
            "notice_id": notice_id,
            "category": category,
            "url": url,
            "description": description,
            "captured_at": timestamp,
            "file": filename,
            "sha256": image_hash
        }

        prev_hmac = self._get_last_hmac()
        chain_input = json.dumps(entry, sort_keys=True) + (prev_hmac or "")
        entry["hmac"] = hmac.new(
            self.secret_key,
            chain_input.encode("utf-8"),
            hashlib.sha256
        ).hexdigest()

        with open(self.manifest_path, "a") as f:
            f.write(json.dumps(entry) + "\n")

        return entry

    def verify_chain(self) -> dict:
        """Verify HMAC chain integrity for audit purposes."""
        if not self.manifest_path.exists():
            return {"valid": True, "entries": 0}

        entries = []
        with open(self.manifest_path) as f:
            for line in f:
                if line.strip():
                    entries.append(json.loads(line))

        prev_hmac = None
        for i, entry in enumerate(entries):
            stored_hmac = entry.pop("hmac")
            chain_input = json.dumps(entry, sort_keys=True) + (prev_hmac or "")
            expected = hmac.new(
                self.secret_key,
                chain_input.encode("utf-8"),
                hashlib.sha256
            ).hexdigest()

            if stored_hmac != expected:
                return {
                    "valid": False,
                    "break_at_entry": i,
                    "notice_id": entry.get("notice_id"),
                    "captured_at": entry.get("captured_at")
                }

            entry["hmac"] = stored_hmac
            prev_hmac = stored_hmac

        return {"valid": True, "entries": len(entries)}

    def _get_last_hmac(self) -> str | None:
        if not self.manifest_path.exists():
            return None
        last_line = None
        with open(self.manifest_path) as f:
            for line in f:
                if line.strip():
                    last_line = line.strip()
        return json.loads(last_line).get("hmac") if last_line else None

Benefit Summary Page Monitoring

Health plan benefit summary pages (SBCs — Summary of Benefits and Coverage) are required by ACA to be publicly available and updated at each plan year. Monitoring these for changes is operationally valuable for brokers, TPAs, and benefits platforms:

def monitor_benefit_summaries(pages: list[dict],
                               output_dir: str = "benefit_snapshots") -> list[dict]:
    """
    Monitor a list of benefit summary pages for changes.

    pages: list of {"id": str, "payer": str, "plan": str, "url": str}
    Returns only pages where changes were detected.
    """
    output_path = Path(output_dir)
    output_path.mkdir(exist_ok=True)
    hashes_file = output_path / "last_hashes.json"

    prev_hashes = {}
    if hashes_file.exists():
        with open(hashes_file) as f:
            prev_hashes = json.load(f)

    current_hashes = {}
    changes = []

    for page in pages:
        resp = requests.get(SCREENSHOT_API, params={
            "url": page["url"],
            "width": 1440,
            "full_page": True,
            "wait_for": "networkidle",
            "format": "png"
        }, headers={"X-API-Key": API_KEY})

        if resp.status_code != 200:
            continue

        image_bytes = resp.content
        image_hash = hashlib.sha256(image_bytes).hexdigest()
        current_hashes[page["id"]] = image_hash

        if page["id"] in prev_hashes and prev_hashes[page["id"]] != image_hash:
            timestamp = datetime.now(timezone.utc).isoformat()
            filename = f"{page['id']}_{timestamp.replace(':', '-')}.png"
            (output_path / filename).write_bytes(image_bytes)

            changes.append({
                "id": page["id"],
                "payer": page["payer"],
                "plan": page["plan"],
                "url": page["url"],
                "detected_at": timestamp,
                "file": str(output_path / filename)
            })

    with open(hashes_file, "w") as f:
        json.dump({**prev_hashes, **current_hashes}, f)

    return changes

Rate Limit Planning for Healthcare Workloads

Healthcare screenshot volumes are lower than fintech or SaaS because the primary triggers are quarterly formulary cycles and annual plan year changes — not continuous event-driven workflows.

The Healthcare Distinction

Healthcare screenshot automation is defined by two constraints pulling in opposite directions:

HIPAA creates a hard ceiling: authenticated patient data cannot be captured, period. The constraint is non-negotiable and reduces the scope of screenshot automation to public-facing pages only.

Regulatory cycles create a hard floor: formulary changes, SBC updates, coverage determinations, and consent flow changes all need documented evidence. The regulatory landscape makes screenshot capture a compliance requirement, not just a convenience.

The result is a pattern where all the tooling from legal tech (HMAC chains, evidence-grade PNG, no modifications) applies, but to a narrower domain: public-facing plan, formulary, and compliance notice pages.

Unlike legal tech's event-driven capture or fintech's daily compliance runs, healthcare screenshot automation is primarily cycle-driven: quarterly formulary checks, annual plan year monitoring, and release-time consent flow documentation. The cadence matches the regulatory calendar, not the transaction log.

Hermesforge Screenshot API: full-page PNG capture, JavaScript rendering, configurable viewports. Get a free API key — 50 calls/day, no signup required.