Share My Records

This workflow demonstrates the operations to allow a patient to share selected, or all, health data resources with a smart health link. The workflow uses GraphQL mutations to create the link as a solution to fulfill the CMS Interoperability Kill the Clipboard pledge.

🚧
NOTE: All workflows and specifications outlined in this guide are subject to change based on final CMS initiative designs and requirements and will adhere to CMS workgroup guidance

Prerequisites

health.network - This workflow requires health.network to be enabled for access to b.well's network connections.
Identity Verification - Verification at IAL2 (Identity Assurance Level 2) must be completed
End-User Authentication - User must be authenticated
Account Creation and Consent - User account and consent must be completed

Environment URL:

Client-Sandbox: https://api.client-sandbox.icanbwell.com/v1/graphql

Workflow Steps

Step 1: Generate a 6-digit passcode

Generate a 6 digit passcode to be used to access the data behind the smart health link.

Step 2: Determine FHIR resources to be shared (optional)

Optionally provide a list of FHIR resources to the user and allow them to select the ones they wish to share.

Not choosing specific resources defaults to sharing all resources that are part of the International Patient Summary (IPS).

[
  {"resourceType": "Patient"},
  {"resourceType": "CarePlan"},
  {"resourceType": "Condition"},
  {"resourceType": "AllergyIntolerance"},
  {"resourceType": "MedicationStatement"},
  {"resourceType": "Immunization"},
  {"resourceType": "Procedure"},
  {"resourceType": "Observation"},
  {"resourceType": "Coverage"}
]

Step 3: Generate the Smart Health Link

The request indicates the optional resources that can be included to filter the link, or be left out to default to sharing all resources along with the passcode required to secure access to the link.

GraphQL Mutation:

mutation CreateHealthLink($input: CreateHealthLinkInput!) {
  createHealthLink(input: $input) {
    id
    identifier {
      system
      value
    }
    description
    resourceType
    date
    status
    subject {
      reference
    }
    context {
      period {
        start
        end
      }
    }
    content {
      attachment {
        contentType
        url
        title
      }
    }
    category {
      coding {
        system
        code
      }
    }
  }
}

Example Variables:

{
  "input": {
    "label": "Health Records",
    "resources": [
      {"resourceType": "Patient"},
      {"resourceType": "CarePlan"},
      {"resourceType": "Condition"},
      {"resourceType": "AllergyIntolerance"},
      {"resourceType": "MedicationStatement"},
      {"resourceType": "Immunization"},
      {"resourceType": "Procedure"},
      {"resourceType": "Observation"},
      {"resourceType": "Coverage"}
    ],
    "securityConfig": {
      "passcode": "743730"
    }
  }
}

The response provides the url within the content.attachment field that needs to be encoded into a QR code along with the context.period indicating the validity of the smart health link.

🚧
NOTE: The IPS viewer returned in the url is a temporary mechanism to display the available data. The final format of the data is to be determined by the CMS Kill The Clipboard workgroup.

Example Response:

{
    "data": {
        "createHealthLink": {
            "id": "e55843b5-131f-5a3a-892e-b2bd4dd17761",
            "identifier": [
                {
                    "system": "http://icanbwell.com/smart-health-links",
                    "value": "irOaHn0Q5wFX9LE7Vu0qi6M4N923ALLP8nKPqTcd8pk"
                },
                {
                    "system": "https://www.icanbwell.com/sourceId",
                    "value": "e55843b5-131f-5a3a-892e-b2bd4dd17761"
                },
                {
                    "system": "https://www.icanbwell.com/uuid",
                    "value": "e55843b5-131f-5a3a-892e-b2bd4dd17761"
                }
            ],
            "description": "Patient Summary",
            "resourceType": "DocumentReference",
            "date": "2025-12-19T19:42:02.887Z",
            "status": "current",
            "subject": {
                "reference": "Patient/person.c2c119e9-4812-4a1a-919e-46eb0fe0356a"
            },
            "context": {
                "period": {
                    "start": "2025-12-19T19:42:02.887Z",
                    "end": "2025-12-19T19:47:02.887Z"
                }
            },
            "content": [
                {
                    "attachment": {
                        "contentType": "application/smart-health-link+json",
                        "url": "https://api-gateway.client-sandbox.icanbwell.com/v1/health-link/viewer.html#shlink:/eyJ1cmwiOiJodHRwczovL2FwaS1nYXRld2F5LmRldi5pY2FuYndlbGwuY29tL3YxL2hlYWx0aC1saW5rL21hbmlmZXN0cy9pck9hSG4wUTV3Rlg5TEU3VnUwcWk2TTROOTIzQUxMUDhuS1BxVGNkOHBrIiwia2V5IjoiVThnY3BpWW9zb3pNanEtcVB0anh2Y3Q1YlhqeUNwSlpRTmdpd0VMMnhiVSIsImV4cCI6MTc2NjE3MzYyMiwiZmxhZyI6IlAiLCJsYWJlbCI6IkhlYWx0aCBSZWNvcmRzIn0",
                        "title": "SMART Health Link Payload"
                    }
                }
            ],
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://hl7.org/fhir/uv/smart-health-cards-and-links/StructureDefinition/ShlPayload",
                            "code": "smart-health-link"
                        }
                    ]
                }
            ]
        }
    }
}

Step 4: Generate QR Code

Encode the content.attachment.url value in the response to a QR code.