SMART Health Check-in
SMART Health Check-in is an open protocol for pre-visit check-in. A provider's web page asks the patient's health app for what the visit needs, such as an insurance card, an allergy list, or a questionnaire, over the W3C Digital Credentials API. The patient approves each item in their app, and a signed, encrypted answer comes back to the same page.
Flexpa runs a test wallet at test.wallet.flexpa.com that implements the protocol's Wallet/Responder role. Use it to build and test a check-in page against a wallet that behaves like a real one, without a phone or a production health app.
The test wallet is experimental. It holds a fabricated sample patient and nothing else, and it does not connect to Flexpa API or to any real records. Do not send real patient data to it, and expect it to change without notice.
#How a check-in works
Two roles take part:
- The verifier is your page. It builds a check-in request that names items by id, wraps it in an ISO mdoc request, generates an encryption key for the session, and calls
navigator.credentials.get().
- The wallet, which the protocol calls the Wallet/Responder, is the patient's health app. It validates the request, shows the patient who is asking and what would be shared, and returns a response bound to your page's origin.
The Flexpa test wallet is a web wallet: your page opens it in a browser tab and hands the request over postMessage. The bytes on the wire are the same ones a native wallet produces, so a check-in page tested against it works unchanged against a platform wallet.
When a request arrives, the test wallet:
- Asks the patient to sign in if they have not on this browser. The sandbox stands in for identity verification with a Simulate IAL2 sign in button and keeps a session cookie on its origin until you sign out.
- Validates the mdoc
DeviceRequest, the SMART request JSON, and the encryption key.
- Binds the session to your page's origin as the browser reports it. A response cannot be replayed to another origin.
- Verifies your optional
readerAuth signature and tells the patient whether the certificate is trusted, valid but unknown, or invalid.
- Matches each
selection.fhir item against its records by declared FHIR profile, profile family, and resource type, and renders each form.fhir questionnaire.
- Lets the patient switch off items or single records and answer forms.
- Builds a response with one status per item, signs it as an mdoc document, encrypts it to your key, and posts it back.
#Try it
The specification site's clinic demo is a complete verifier. Open it with the Flexpa test wallet selected, or paste the link:
https://smart-health-checkin.org/client/demo/#wallets=https%3A%2F%2Ftest.wallet.flexpa.com%2Fwallets.json&wallet=flexpa
- Click Check in with Flexpa Health Wallet.
- The wallet opens in a tab. On a first visit it asks you to Simulate IAL2 sign in; after that it goes straight to the request until you sign out. It shows the requesting origin, the signature verdict, and each requested item with the records it would share. Toggle items or records, answer the PHQ-2, then click Share.
- The demo decrypts and verifies the response, reports You're checked in, and lists one status per item. Developer detail shows the verified artifacts.
Add &scenario= to try the demo's other request templates: insurance-only, new-patient, phq2-dayof, allergy-review, or medlist-refresh. In Demo controls, turn on post to FHIR with the public HAPI server to see the response written as a FHIR transaction.
#Point your check-in page at the test wallet
The test wallet publishes a wallet registry at https://test.wallet.flexpa.com/wallets.json. With the specification's JavaScript client, list it as a web wallet and let the patient choose it:
import { credentialGetterFor, requestCheckin, resolveResponders } from '@smart-health-checkin/client';
const responders = await resolveResponders({
platform: true,
webWallets: 'https://test.wallet.flexpa.com/wallets.json',
default: 'flexpa',
});
const flexpa = responders.find((responder) => responder.id === 'flexpa');
const response = await requestCheckin(
{
purpose: 'Before your visit',
items: [
{
id: 'coverage',
title: 'Insurance coverage',
content: { kind: 'selection.fhir', profilesFrom: ['http://hl7.org/fhir/us/carin-bb'] },
accept: ['application/smart-health-card', 'application/fhir+json'],
},
],
},
{ getCredential: credentialGetterFor(flexpa) },
);
Or open the wallet directly:
import { createWebWalletCredentialGetter, requestCheckin } from '@smart-health-checkin/client';
const response = await requestCheckin(myRequest, {
getCredential: createWebWalletCredentialGetter({ walletUrl: 'https://test.wallet.flexpa.com/wallet.html' }),
});
Call requestCheckin from a click handler. The wallet tab is a popup, and browsers require a user gesture to open one. The client library decrypts the response, checks both signatures, and cross-validates it against your request before it returns.
#What the test wallet holds
The sample patient is fabricated. Every FHIR resource declares the profiles it conforms to, which is the evidence selection.fhir matching prefers.
| Records | Details |
|---|
| Patient | US Core Patient |
| Coverage | CARIN Blue Button and CARIN Digital Insurance Card Coverage, with the payer Organization |
| Insurance card | A SMART Health Card carrying the Patient, Coverage, and Organization, signed by a test issuer |
| Allergies | Three US Core AllergyIntolerance records, one deliberately sparse |
| Conditions | Two US Core problem-list Conditions |
| Medications | Two US Core MedicationRequests |
| Immunizations | Two US Core Immunizations |
| Observations | Blood pressure, body weight, and a hemoglobin A1c lab result |
The wallet's home page lists these records and lets you add other test records: paste or upload FHIR R4 JSON, a .smart-health-card file, or a bare SMART Health Card JWS, or fetch a Bundle from a FHIR endpoint such as Flexpa API in test mode. Records stay in your browser's storage.
#What it supports
| Area | Support |
|---|
| Selectors | selection.fhir with profiles (including versioned canonicals), profilesFrom, and resourceTypes; form.fhir with an inline Questionnaire or a canonical the wallet knows, such as the PHQ-2 (https://fhir.loinc.org/Questionnaire/55757-9) |
| Media types | application/fhir+json (FHIR 4.0.1) and application/smart-health-card |
| Statuses | fulfilled, partial, unavailable, declined, and unsupported, one per item |
| Fulfillment | One artifact can answer several items; an item can return a card and FHIR together |
| Reader authentication | Verified and classified; the trust list is empty, so a valid signature shows as valid, untrusted |
| Keys | Fresh issuer and device keys for every response, so responses are not linkable across verifiers |
Limits to know about:
- It is a web wallet only. A phone's built-in wallet picker will not offer it, and a kiosk flow's hand-off page must list it in its own registry.
- It holds FHIR 4.0.1 records. A request that accepts only other FHIR releases gets
unsupported.
- Questionnaire item types it cannot render, such as attachments, come back
unsupported with the reason.
#Next steps