CMS Aligned Networks
Flexpa was selected as a CMS Aligned Network Early Adopter in July 2025. As part of this initiative, we pledged to build capabilities that empower patients to retrieve their health records and share them with providers — eliminating clipboards, portal logins, and repetitive paperwork.
This page documents the two core capabilities Flexpa is delivering under the pledge, their current status, and the timeline for availability.
#Capability 1: SMART Health Cards and Links
Generate in-app SMART Health Cards and Links (QR codes for health records)
#What it is
Patients retrieve their health records through Flexpa and receive a SMART Health Link — a secure, encrypted URL rendered as a QR code. At a provider's office, the patient presents the QR code. The provider scans it, decrypts the payload, and imports it directly into their EHR. No faxes, no clipboard forms, no manual data entry.
The SHL payload contains a FHIR Bundle with the patient's clinical data as discrete FHIR resources, plus a DocumentReference containing a rendered PDF of the patient summary for display in systems that do not support FHIR. The PDF is generated automatically by the $summary operation and included as a base64-encoded attachment in the Bundle.
Flexpa's implementation follows the Patient-Shared Health Document via SMART Health Links specification (draft v0.4.0), as developed by the CMS Kill the Clipboard Working Group. Note that working group alignment on this specification is still in progress.
#Status and timeline
Flexpa's SMART Health Links API is live in production with full STU1 specification compliance. Applications can create, list, and revoke SMART Health Links today.
The API supports all three content types defined in the spec:
application/fhir+json — FHIR Bundles, DocumentReferences, or any FHIR resourceapplication/smart-health-card — Signed JWS Health Cards for tamper-proof credentialsapplication/smart-api-access — SMART Access Token responses for follow-on API calls
To satisfy the requirements of the pledge, we are introducing support for the International Patient Summary (IPS) and extending the $summary operation to support section filtering so patients can select the data they need.
| Date | Milestone | Environment | Status |
|---|
September 2025 | SMART Health Links API (STU1) | Live mode | Available |
February 16 | $summary operation (IPS) | Test mode (static fixture) | Available |
February 18 | _section filter support for $summary | Test mode (static fixture) | Available |
February 24 | DocumentReference PDF packaged with IPS | Test mode (static fixture) | Available |
| March 3 | $summary without fixture | Test mode | Upcoming |
| March 10 | $summary from live data | Live mode | Upcoming |
#How to use it
Create a SMART Health Link from any FHIR data retrieved through the Flexpa API. The API returns a shlink:/ URL that can be rendered as a QR code for the patient.
A typical workflow:
- Patient authorizes via Flexpa Consent
- Your application retrieves FHIR data via the Flexpa API — use the Patient $summary operation to generate a structured IPS document. The
_section parameter lets patients choose which categories of data to share (e.g., allergies and medications only)
- POST the data to the SMART Health Links API to generate an encrypted link
- Render the link as a QR code for the patient to store or share
curl -X POST https://api.flexpa.com/smart/health-links \
-H "Authorization: Bearer sk_test_your-secret-key" \
-H "Content-Type: application/json" \
-d '{
"files": [{
"contentType": "application/fhir+json",
"content": {
"resourceType": "Bundle",
"type": "collection",
"entry": [
{"resource": {"resourceType": "Patient", "id": "123"}},
{"resource": {"resourceType": "Condition", "id": "456"}}
]
}
}],
"user": {"externalId": "patient-123"},
"label": "Medical Records"
}'
#International Patient Summary (IPS)
The International Patient Summary (IPS) is an HL7 FHIR Implementation Guide that defines a minimal, standardized clinical document for cross-border and cross-organization patient data exchange. An IPS document is a FHIR Bundle of type document containing a Composition resource that organizes a patient's clinical data into sections: allergies, medications, problems, immunizations, procedures, results, and more.
Flexpa generates IPS documents locally from data retrieved through the Flexpa API using the Patient $summary operation. The generated document conforms to the IPS Composition profile, including:
- 14 standardized sections defined by LOINC codes (allergies, medications, problems, immunizations, procedures, results, vital signs, social history, devices, plan of treatment, functional status, past illness, pregnancy history, advance directives)
- Status-based filtering — only clinically relevant resources are included (e.g., active medications, completed immunizations)
- Section narratives — each section includes a human-readable XHTML narrative for display
- Empty section handling — sections with no data include an
emptyReason of unavailable; sections excluded by the patient include an emptyReason of withheld
- Confidentiality tagging — the Bundle carries a
meta.security high water mark reflecting the most restrictive confidentiality code across included resources
#Patient-selected sections
The _section query parameter on $summary lets patients choose which categories of data to include. This is the mechanism for patient-directed consent: the application presents section choices to the patient, then passes their selections to the API.
When _section is provided, excluded sections still appear in the Composition (preserving the IPS structure) but contain no entries and are marked with emptyReason of withheld. Only resources referenced by included sections are present in the Bundle.
A typical IPS-to-SHL workflow:
- Patient authorizes via Flexpa Consent
- Your application presents section choices (allergies, medications, problems, etc.)
- Call
$summary with the patient's selected _section values
- POST the IPS document Bundle to the SMART Health Links API
- Render the resulting
shlink:/ URL as a QR code for the patient
The receiving provider scans the QR code and receives the IPS document — a structured, standardized summary of exactly the data the patient chose to share.
1. Generate IPS
GET
/fhir/Patient/$PATIENT_ID/$summaryACCESS_TOKEN=flexpa-link-access-token
# Patient selected: allergies, medications, problems
curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$summary?_section=allergies&_section=medications&_section=problems' \
-H "Authorization: Bearer $ACCESS_TOKEN"
2. Create SHL
# Pass the IPS document Bundle directly to the SHL API
curl -X POST https://api.flexpa.com/smart/health-links \
-H "Authorization: Bearer sk_test_your-secret-key" \
-H "Content-Type: application/json" \
-d '{
"files": [{
"contentType": "application/fhir+json",
"content": { "... IPS Bundle from step 1 ..." }
}],
"user": {"externalId": "patient-123"},
"label": "Patient Summary"
}'
#Test mode
In test mode, $summary currently returns an IPS document built from a static fixture rather than the patient's actual $everything data.
The fixture is a Synthea-generated bundle and does not correspond to the data returned by other FHIR queries for the same patient authorization.
A future release (see timeline above) will build the IPS from live test mode data, matching the behavior of live mode.
You can view the test mode $summary output here: test-mode-summary.json.
#Returning visit records
Working group consensus on this process has not yet been achieved. The specification and workflow described below may change.
As part of the Kill the Clipboard pledge, we are also developing support for returning post-visit summaries to patients as SMART Health Links. After an appointment, providers generate an SHL containing the visit summary (sourced from a C-CDA document) that the patient can open in any SHL-aware app. See our technical proposal for implementation details.
#Capability 2: IAL2 digital identity for record access
Demonstrate IAL2 OIDC token use (no portal logins)
#What it is
Instead of requiring patients to remember login credentials for every hospital and insurer portal, Flexpa uses Identity Assurance Level 2 (IAL2) digital identity verification. A patient verifies their identity once through CLEAR or ID.me, and Flexpa discovers and retrieves their records from across the TEFCA network — 56,000+ facilities nationwide — without any additional logins.
This is the CMS vision: "If a patient uses a digital identity credential (through a CMS-approved IAL2 provider), all nodes must return full records without requiring knowledge of specific providers, portal accounts, or additional interactions."
#How it works
- Patient initiates a connection through Flexpa Consent with TEFCA enabled
- Patient verifies their identity via CLEAR or ID.me (one-time process, typically under a minute for existing users)
- Flexpa queries the TEFCA network using verified demographics to discover patient records across participating facilities
- Clinical documents (C-CDA) are retrieved from matching facilities and returned as FHIR DocumentReference resources
For returning users with existing CLEAR or ID.me credentials, the entire flow takes under a minute. First-time identity verification takes 3-7 minutes.
#Status and timeline
| Date | Milestone | Environment | Status |
|---|
February 17 | TEFCA IAS with C-CDA documents | Test mode | Available |
March 3 | TEFCA IAS with C-CDA documents | Live mode | Available |
March 3 | C-CDA to FHIR resource transforms | Test mode | Available |
| March 10 | C-CDA to FHIR resource transforms | Live mode | Upcoming |
C-CDA documents are returned as FHIR DocumentReference resources containing the full clinical document (Continuity of Care Documents, discharge summaries, clinical notes). C-CDA to FHIR transforms convert these documents into structured FHIR resources (Condition, MedicationRequest, Observation, etc.) for easier programmatic use.
Facilities connected via TEFCA typically return clinical data as C-CDA (Consolidated Clinical Document Architecture) documents: XML-based clinical documents such as Continuity of Care Documents (CCDs) and discharge summaries.
While these documents contain rich clinical data, they require parsing and transformation to be useful in FHIR-based workflows.
Flexpa automatically transforms C-CDA documents into structured FHIR resources. When a C-CDA document is retrieved from a facility, Flexpa extracts the clinical data and creates discrete FHIR resources (Condition, MedicationRequest, Observation, Procedure, AllergyIntolerance, Immunization, and more) that can be queried individually through the Flexpa API.
C-CDA to FHIR transforms are currently available in test mode, with live mode support coming March 10 (see timeline).
#DocumentReference tagging
Each DocumentReference resource includes a tag indicating its transformation status. Use this tag to determine whether structured FHIR resources have been extracted from the document.
| Tag code | Meaning |
|---|
transformed | Successfully converted to FHIR resources |
not-ccda | Not a C-CDA document (PDF, HTML, or plain text) — no transformation attempted |
not-transformed | C-CDA document but conversion was unsuccessful — the document may be malformed, missing required elements, or empty |
The tag uses the system https://fhir.flexpa.com/identifiers/CcdaToFhir:
{
"meta": {
"tag": [{
"system": "https://fhir.flexpa.com/identifiers/CcdaToFhir",
"code": "transformed",
"display": "C-CDA 2.1 transformed to FHIR resources"
}]
}
}
#Provenance tracking
For each successfully transformed document, Flexpa creates a Provenance resource that links the derived FHIR resources back to the source DocumentReference. This allows your application to trace any resource to the document it was extracted from.
{
"resourceType": "Provenance",
"target": [
{ "reference": "Condition/uuid-1" },
{ "reference": "MedicationRequest/uuid-2" },
{ "reference": "Observation/uuid-3" }
],
"recorded": "2026-03-03T14:30:00Z",
"activity": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
"code": "TRANS",
"display": "transform"
}]
},
"agent": [{
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
"code": "assembler"
}]
},
"who": {
"display": "Flexpa CCDA-to-FHIR"
}
}],
"entity": [{
"role": "source",
"what": { "reference": "DocumentReference/the-source-doc-id" }
}]
}
Query Provenance resources via $everything or search directly to find all resources derived from a specific document:
curl 'https://api.flexpa.com/fhir/Provenance?entity=DocumentReference/<doc-id>' \
-H "Authorization: Bearer <access_token>"
#How to use it
Enable TEFCA by passing the flexpa_ial2_mode query parameter to the authorization endpoint. The patient experience and developer integration follow the same patterns as other Flexpa data sources — FHIR resources are returned via the standard Flexpa API.
import { FlexpaClient } from '@flexpa/node-sdk';
const authUrl = FlexpaClient.getAuthorizationUrl({
publishableKey: 'pk_test_...',
redirectUri: 'https://example.com/callback',
scope: ['launch/patient', 'offline_access'],
state: 'random-state',
_experimentalParams: {
flexpa_ial2_mode: 'true',
},
});
#Test credentials
Use the IAL2 test credentials for ID.me or CLEAR to complete identity verification in test mode. Both are IAL2-compliant identity providers.
#End-to-end flow
Here is what happens when a patient completes a TEFCA consent:
- Authorization — Your application redirects the patient to the Flexpa authorization URL with
flexpa_ial2_mode: 'true'.
- Consent — The patient completes the Flexpa Consent flow: IAL2 identity verification, patient discovery (XCPD), document retrieval (XCA), and facility sign-in if applicable. In test mode, Flexpa also injects fixture documents to ensure consistent test data.
- Callback — Flexpa redirects to your
redirect_uri with an authorization code.
- Token exchange — Your server exchanges the code for an access token via
POST /oauth/token (standard OAuth PKCE flow).
- FHIR queries — Use the access token to query FHIR resources.
#Querying FHIR resources
Once the consent is complete and you have an access token, use it to query the Flexpa API.
Flexpa does not block the token exchange while data syncs.
Your application receives the access token immediately, and data becomes available as the sync progresses in the background.
Until the sync completes, FHIR queries return 429 responses.
There are two ways to handle this:
- Polling — Retry FHIR requests until you receive a
200. The Node SDK handles this automatically.
- Webhooks — Subscribe to sync completion events via webhooks and query FHIR resources only after you receive a notification.
A single consent can include multiple patient authorizations. Some facilities discovered through TEFCA respond via direct FHIR API access instead of XCA (e.g., Epic Nexus participants), which creates an additional patient authorization requiring sign-in. Each authorization has its own Patient resource, so start by searching for all patients associated with the consent:
curl https://api.flexpa.com/fhir/Patient \
-H "Authorization: Bearer <access_token>"
Then, for each patient, use $everything to retrieve all resources associated with that patient:
curl https://api.flexpa.com/fhir/Patient/<patient-id>/\$everything \
-H "Authorization: Bearer <access_token>"
The resource types returned by $everything depend on how the facility was connected. Facilities connected via XCA document exchange return C-CDA clinical documents as DocumentReference resources. Facilities connected via direct FHIR API access return structured FHIR resources directly. When C-CDA to FHIR transforms are enabled, eligible C-CDA documents are also converted into structured FHIR resources. Check the DocumentReference tag to determine the transformation status of each document.