How to Use SMART Health Links to Return Visit Records to Patients

Upcoming Webinar: Flexpa is hosting a joint webinar with HealthLX on Open Sourcing Consumer Payer Data on September 23rd.

Overview

The following is based on an open proposal Flexpa is developing to realize the Kill the Clipboard pledge we made under the CMS Aligned Networks initiative. This proposal represents our views alone. We are open to joining any and all co-pledges as collaborators.

As signers of the Kill the Clipboard pledge, EHRs, Providers, Payers, and Apps pledged to:

... empower patients to retrieve their health records from CMS Aligned Networks or personal health record apps and share them with providers via QR codes or Smart Health Cards/Links using FHIR bundles. When possible, we will return visit records to patients in the same format.

Our proposal: Use SMART Health Links (SHLs) as the standard transport format for after-visit summaries to patients. EHRs generate SHL links containing encrypted FHIR resources. Providers share these links through any channel. Patients open them in any SHL-aware app.

SHL workflow diagram showing EHR generating link, provider sharing it, and patient opening in app

What SMART Health Links (SHLs) give you

A SMART Health Link is a single link or QR that points to a small manifest of encrypted files (e.g., FHIR resources, optional SMART-on-FHIR access token).

The link encodes the decryption key and flags like L (long‑lived/updates), P (passcode required), or U (direct file, no manifest). The payload is typically shared as https://viewer.example/#shlink:/... so the secret stays in the URL fragment.

The receiving app (any SHL‑aware app or even a web page) decodes the SHL, POSTs to fetch the manifest (with optional passcode), then downloads and decrypts the files. For "Plain SHL," a baseline client only needs to parse → fetch → decrypt.

Files in the manifest can be:

• application/fhir+json — any FHIR resource or Bundle (e.g., Composition/Bundle for the visit summary; DocumentReference for a PDF).
• application/smart-api-access — a SMART Access Token Response with aud (FHIR base URL) and optional query hints for follow‑on API calls.
• application/smart-health-card — signed JWS Health Cards, if you include verifiable fragments.

Delivery is flexible: email/SMS/portal or QR. QR use is explicitly supported.

Use cases explicitly include clinical/encounter summaries after a visit that the patient can open in a browser or any SHL‑aware app.

What you actually put in the SHL

The content of the SHL is ultimately sourced from a C-CDA document. Regardless of how resources are represented, the content of the SHL could be any of the following options:

Option 1: Static one‑time summary

A static one-time summary equivalent to, and built from, a corresponding C-CDA document is straightforward:

• Set flag: "U" indicating the direct file access pattern is supported
• Provide a single raw FHIR resource consisting of either:
  1. A C-CDA document as a US Core-implementing DocumentReference and associated attachment, or;
  2. A C-CDA document mapped to a FHIR Composition and associated resources following the C-CDA on FHIR IG.
• The consumer app / health record wallet does one GET and decrypts.

{
  "resourceType": "Bundle",
  "type": "document",
  "entry": [
    { "resource": { "resourceType": "Composition" ... }},
    { "resource": { "resourceType": "Patient" ... }},
    { "resource": { "resourceType": "Practitioner" ... }},
    { "resource": { "resourceType": "Encounter" ... }}
  ]
}

Option 2: Upgrading to Patient Access API

The SHL spec provides a pathway to include information to help establish a consumer-mediated SMART on FHIR connection to the data source. In this option, we make available a FHIR resource which helps an app establish a Patient Access API connection.

• Set flag: "U" indicating the direct file access pattern is supported
• Provide a single raw FHIR resource, specifically an Endpoint, minimally with a name, connectionType, and address
• The consumer app / health record wallet does one GET and decrypts. If the Endpoint is one to which it has a known connection, it initiates a standalone app launch
• The encounter summary is otherwise then delivered through the established Patient Access API

{
  "resourceType": "Endpoint",
  "name": "Doctors-R-Us",
  "address": "https://fhir.example.org",
  "connectionType": {
    "system": "http://terminology.hl7.org/CodeSystem/restful-security-service",
    "code": "SMART-on-FHIR"
  },
  "payloadType": [
    {
      "system": "http://terminology.hl7.org/CodeSystem/endpoint-payload-type",
      "code": "none"
    }
  ]
}

Option 3: Rich manifest

Or, use a manifest with multiple encrypted files, with a mix of all of the above options:

• application/fhir+json → Bundle (document) for the structured summary
• application/fhir+json → DocumentReference for a C-CDA
• application/smart-api-access → SMART token response with aud and optional query hints like ["Observation?encounter=123", "CarePlan?patient=..."] so the receiving app can hydrate details on demand (no long‑term OAuth setup).

Nice to Haves

Use flag: "L" to make the link auto‑update (e.g., late lab results). Clients poll at the server's suggested cadence; you can expire/revoke at any time.

Use flag: "P" to require an out‑of‑band passcode; the server enforces attempt limits.

If you want a global, portable summary instead of an AVS‑only slice, publish an IPS (International Patient Summary) Bundle through SHL — the IG includes working examples.

The Vision

With SMART Health Links, patients can access for their own healthcare records - including post-visit summaries - without ever involving complex national HIE networks, IAL2 credentials, or traditional portal logins.

With flexible implementation options and the HL7 standards developement process (SMART Health Cards & Links IG is now STU1), it's now technically possible to deliver records directly to patients in natively electronic formats.

Flexpa is committed to bringing this vision to life.

That's why we became a Kill the Clipboard pledge and it's also why we're making available our fully featured implementation of a SMART Health Links API to partners who want to help. With support for passcodes, long-term links, both manifest request APIs, and client-side encryption, our SMART Health Links API exists to accelerate adoption.

Schedule a demo or talk to us directly at partnerships@flexpa.com.