Skip to main content

HealthShare Personal Community API Guide



1. Introduction

Personal Community provides a series of of REST and SOAP APIs that allow trusted external systems to interact with the patients and the application.  This guide is intended to provide a comprehensive list of available APIs for external systems to use. Actual use and configuration of these APIs are in the corresponding setup guides.

2. Available APIs

2.1. Onboarding and Account Management APIs

The series of onboarding and account management APIs are designed to drive adoption of Personal Community.   

2.1.1. Enrollment Status

The Enrollment Status API is designed to be used prior to calling any other Personal Community API.  This API will return the status of the current patient, so the workflow can act accordingly. 

2.1.2. Invitation to Enroll

This Invitation to Enroll API allows an organization to automatically send a digital invitation to patients that are not yet enrolled in Personal Community.  This API is designed to send an SMS message, email message, or both to the prospective member, in that member's preferred language (if configured in Personal Community).  

The Invitation to Enroll API is best used when External Credentials or Self-Enrollment is enabled.  

2.1.3. Enrollment

The Enrollment API supports the automated enrollment workflow for Personal Community.  Automated enrollment allows an organization to create Personal Community accounts programmatically from their external systems, such as their EMR or CRM.  This API will provision the patient's account in Personal Community and notify the patient that they have been enrolled.  

2.1.4. Proxy Management

proxy user   (also known as a   proxy ) is a patient’s legal representative for interactions with the organization’s version of the Personal Community. One member may serve as a proxy for another for a number of reasons, such as:

  • A parent or guardian representing a child.

  • A family member or guardian representing someone with a temporary or long-term incapacity, such a patient receiving anesthesia or suffering from dementia, respectively.

  • A family member representing another family member for administrative or convenience reasons, such as one spouse representing another.

The patient being represented in the  proxy relationship  is known as the  principal .

The Proxy Management API allows an external system to programmatically create proxy relationships between two existing Personal Community members.

2.2. Event Based APIs

The series of event based APIs are designed to increase the usage of Personal Community members.  These APIs are called based on events in a patient's medical care, and prompt the member to return to Personal Community to complete a given action.

2.2.1. Secure Messaging 

The Secure Message API allows an organization to send a message to a patient's inbox within Personal Community.  This API is intended to be used when delivering messages that may contain protected health information.  This message is delivered to the patient's inbox within Personal Community, and the patient is notified that there is a new message.

This API supports two types of workflows:

  • Integration with an external messaging system for bi-directional communication → in this workflow, patients and providers are using messaging to support communication. The API is used to integrate the existing external messaging system into Personal Community
  • Triggered messages from workflows → In this workflow, messages are automatically sent based on actions within the existing application.  For example, when a letter is created for the patient it can be delivered to their inbox instead of being mailed.

Personal Community provides both a REST and SOAP version of the APIs. New integrations should use the REST API as that will be enhanced moving forward.

2.2.2. Notifications

The Notification API is a REST API that allows an organization to notify patients of new information, such as new results, or actions available in Personal Community, such as Flu vaccination appointments becoming available. This type of notification is not delivered to the member's Personal Community inbox.

Personal Community ships with a notification for use when a member has new data in their health record. You can customize the language of this notification and you can add notifications for different types of events as well.

2.2.3. Direct Communication   

The Direct Communication API is a SOAP API. Usage of the Notification REST API is encouraged over the Direct Communication SOAP API. Any future enhancements to notification functionality will only be developed against the Notification REST API. The Direct Communication SOAP API may eventually be deprecated. 

The Direct Communication API allows an organization to notify patients when an event occurs, such as new data becoming available.  The Direct Communication API is part of the Secure Messaging API, allowing an organization send notifications directly to a member, to a member’s proxy, or both. Unlike the Secure Message, this type of notification is NOT delivered to the member’s Personal Community inbox.

Personal Community ships with a notification for use when a member has new data in their health record. You can customize the language of this notification and you can add notifications for different types of events as well.

2.2.4. Patient Tasks

An integral part of an organization's patient engagement strategy is the ability to provide patients with the ability to receive and complete task items prior to appointments and visits, or after they have been discharged. Often times, these are done over the phone, or in person when the patient arrives to check in for their service, often using paper forms to capture assessments and consent.

The Patient Task API allows organizations to send digital versions of education, instructions, and forms to patients within Personal Community. Additionally, organizations may request that patients upload documentation as part of these tasks.   If a patient has a task to complete, the   Home    page will now include a  To Do   box.  This box will list any outstanding tasks that have been sent to a patient. 

2.3. System Configuration APIs

The series of system configuration APIs are designed to allow sites to programmatically create and manage certain setup within Personal Community.

2.3.1. Clinical Group and Provider

The Clinical Group and Provider API is intended to be used alongside the secure messaging functionality within Personal Community.  For secure messaging to be enabled within Personal Community, the clinical groups and associated providers that will accept and send messages must be configured in the Workbench.  This API allows for an external system to send updates to the Workbench to ensure the list of available providers is accurate.

2.3.2. Web Application Information

The Web Application Information API can be used to retrieve the list of information about the available web applications for Personal Community. This information can the be used to automatically populate the endpoints for future calls, as necessary.

3. Using the Personal Community APIs to Drive Adoption

All of the Personal Community APIs are designed to be incorporated into standard workflows within an organization. By combining these APIs, organizations can drive adoption and use of Personal Community by your patient population. 

In this example, the workflow begins when an action is triggered for the patient, this includes either creating a patient task, sending an inbox message, or sending a notification. The Personal Community APIs can then be combined to decide whether to send the action, invite the patient to enroll, or enroll the patient.

4. Documentation

API Book Chapter
Enrollment Status HealthShare Personal Community Onboarding and Account Management Setup Guide 6.2.1. Using the Enrollment Status REST API
Invitation to Enroll HealthShare Personal Community Onboarding and Account Management Setup Guide 2. Using the Invitation to Enroll API
Enrollment HealthShare Personal Community Onboarding and Account Management Setup Guide 3.1.3. About Automated Enrollment
Proxy Management HealthShare Personal Community Onboarding and Account Management Setup Guide 8. Proxy Management
Messaging

HealthShare Personal Community Messaging: Provider Initiated Messages from External Systems Setup Guide

HealthShare Personal Community Messaging: Sending Messages and Notifications from the Unified Care Record Setup Guide

Full Guides

Notification / Direct Communication

HealthShare Personal Community Messaging: System Inititated Notifications from External Systems Setup Guide

HealthShare Personal Community Messaging: Sending Messages and Notifications from the Unified Care Record Setup Guide

Full Guides
Patient Task HealthShare Personal Community Patient Entered Data: Patient Task Setup Guide Full Guide
Clinical Group and Provider HealthShare Personal Community Messaging: Provider and Clinical Group Data Setup Guide 3. Adding Provider and Clinical Group Data Using the API