Skip to main content

HealthVault platform technical overview

This article provides a brief technical overview of HealthVault, including options for applications to connect and exchange data with HealthVault users.

This article contains the following sections:

Last updated: June 2013

Other resources

For information about how to make a device compatible with HealthVault, see How to make your device HealthVault compatible.

Core concepts

HealthVault terminology

Application ("app")The third-party software or service that connects to HealthVault.

A HealthVault account.

  • A Person has a PersonID which uniquely identifies, to the app, the account that has authorized the app.
  • The term People or Persons is used in the HealthVault API to indicate a plurality of accounts.
  • In the HealthVault shell text, person is used interchangeably with record, but in the API Person always means account.

A container of health data for an individual.

  • The data contained within a record is data for a single individual.
  • A Person can have access to multiple records.
    • For instance, a parent maintains a record for herself and separate records for her children. She acts as a custodian of these records because she manages their health.
    • The HealthVault Shell allows creating new records.
  • The RecordID uniquely identifies, to the app, a record that is authorized to be accessed by the app.
  • Data operations are always performed on a target record.

A single health data item that is stored within a record.

  • For example, a Weight thing represents an instance of a Weight measurement.
  • The HealthVault types browser lists all HealthVault thing types.
  • Things are referred to as HealthRecordItems in the .NET SDK.
Person-Record Authorization (or simply Person Sharing)

A feature in HealthVault that allows a Person to share a record with another Person.

  • For instance, an elderly user authorizes her adult child to access her record. The child is able to manage the elderly parent’s record.
  • Person sharing is initiated through the Shell.
  • Person sharing allows sharing records with other HealthVault People but it is NOT intended to be used for sharing records with healthcare professionals. (Sharing data with healthcare professionals is accomplished with an application.)
Application-Record Authorization (or simply, Record Authorization)

A feature in HealthVault that allows a Person to authorize an Application to access a record.

  • The Person must have access to the record in order to authorize an Application to access it.
  • A Person can't authorize an Application for more access than the Person has to the record.
Authorization Rules

Rules that specify the type of access an Application is requesting from the user.

  • For instance, Read/Write access to Weight data and Read access to Medications.

Healthcare professionals and HealthVault

Healthcare professionals DON’T log in to the HealthVault Shell to interact with People.

Individual users (that is, consumers and patients) interact with HealthVault by:

  • Logging-in and using the HealthVault Shell UI
  • Using applications and devices that connect with HealthVault

Healthcare professionals interact with HealthVault by: 

  • Using HealthVault-connected applications such as EMRs, provider portals, or custom applications.

Healthcare providers do not have PersonIDs within HealthVault because they access HealthVault through an external app rather than through their own HealthVault account.

The HealthVault web service

HealthVault is an XML-over-HTTP web service exposing a set of XML-based methods that developers can leverage to build applications that connect to HealthVault. Any modern technology environment that supports reading and writing XML can be used to build applications for HealthVault.

Applications can connect to HealthVault using a number of technology stacks and development platforms. See SDKs for HealthVault for list of all available SDKs.

Establishing a connection with the user

HealthVault users must consent to their data being accessed by applications. The first step when you connect an application to HealthVault is to determine how you will establish a connection with the user. Once the connection is established, the app can access the user’s record.

There are a few options for establishing a connection, described in the following sections.


In this model, the application has a user-facing website (a HealthVault application). Upon visiting the site the Person is redirected to HealthVault to sign-in or create an account and authorize the application to access a record.

Subsequently, HealthVault redirects the Person back to the app.

The app uses the PersonID and RecordID to access data in the record. 

The .NET SDK wraps this functionality in the HealthServicePage class. ASP.NET pages that derive from HealthServicePage inherit this behavior.

For more information, see HealthVault web connectivity.

The following are also useful resources to implement this approach:


In this model, the application runs on a mobile device or tablet that communicates with HealthVault directly.

Upon first use of the app, the Person is directed to HealthVault to sign-in or create an account and authorize the application to access a record. Subsequently, the application accesses HealthVault without requiring user authentication.

You can read the brief HealthVault Mobile intro for more information.

The HealthVault mobile SDKs wrap up this functionality. See SDKs for HealthVault for a list of all available mobile SDKs.

Patient Connect

This approach is useful for establishing authorization for a connection with a Person's HealthVault record when the health provider doesn't have or want a user facing website.

For example, a provider’s EHR system might use Patient Connect to connect to a user's record.

The clinic's app creates a “connect request” in HealthVault using a secret question/answer. The patient goes to HealthVault to authenticate the connection with the correct secret answer. The application polls HealthVault at regular intervals to check for new authentications. The application can then use offline connections to sync data between the clinical system and the HealthVault record. For more information about Patient Connect, see Establishing authorization with a user using Patient Connect.

The .NET SDK wraps this functionality in the in the PatientConnection class.

Drop-Off Pick-Up (DOPU)

In this approach the application drops off data without establishing any long-term authorization to a record.

For example, an EHR product within a clinic uses DOPU at discharge time to send patients a visit summary.

After each drop-off, the user must visit the HealthVault package pickup URL to accept the data, since no long-term authorization is established.

This data pickup workflow is nearly identical to the Patient Connect workflow, the major difference being that at the end of the workflow, the data is incorporated into the record instead of authorization being established.

DOPU is also simpler than Patient Connect, because the app doesn't need to poll for data changes. For more information about DOPU, see HealthVault Drop-Off and Pick-Up (DOPU).

The .NET SDK wraps this functionality in the Microsoft.Health.Package.ConnectPackage class.

Using Direct messaging (available in the U.S. only)

HealthVault provides support for the protocols for Direct messaging within the U.S.

For more information about Direct messaging, including how to send data to patients using Direct messages, see the following posts on the Family Health Guy blog:

Also see the HealthVault Message Center application.

Exchanging data

Once the app's connection with the person's record is established, the question is how to read/write data to/from HealthVault.

There are two key methods for this: GetThings and PutThings. New data is written using the PutThings method and data is retrieved using the GetThings method. For more information, see Querying data and Writing data.

In the .NET SDK this functionality can be found in the following classes:

Detecting changes

Applications may want to detect changes in data in a HealthVault record. There are a few options for accomplishing this.


In this approach, the app calls GetUpdatedRecordsForApplication to detect records authorized to the app that have changed since a specific time. The .NET SDK method is Microsoft.Health.HealthVaultPlatform.GetUpdatedRecordsForApplication. (Also see Microsoft.Health.ApplicationConnection.GetUpdatedRecordsForApplication.)

The app can then read the data that has changed.


When there are changes to records to which the application is authorized, the app receives a notification. Once notified, the app can read the data that has changed.

See the HealthVault Eventing concept article for more information about using an event-driven approach to detecting changes.

HealthVault data storage model

Health data is segmented per-record in HealthVault.

Data exchange operations in HealthVault are performed against a single record.

User’s MUST consent to their records being accessed by the app before it can read the data.

Data exchange is always performed at an individual record level. To perform cross-record queries, analysis, aggregation, etc., an app can read multiple records into its own cache. Analysis is done in the app rather than directly on HealthVault.

HealthVault data model

Things in HealthVault have common data elements as well as a schematized section specific to each type of data.

The common fields include:

Version StampIdentifies the specific instance of a thing. When a thing is updated, the version stamp changes.
TypeIDSpecifies the data type of the “schematized” portion of the thing.
AuditsThe source of the data, when it was created/last updated, by whom, etc.
BlobsAllows unstructured data to be associated with structured data. Medical images are a good example.
SignatureOptional digital signature on an item, which can be used to validate integrity and source of data.
Related ItemsAllows creating relationships between things. For instance a “Medication” used to treat a “Condition” could be linked through a Related Item.
Client IDAllows apps to define their own identifier for a thing.
NotesFree-form text notes.
Data-XMLThe schematized portion of a thing. The schematized portion represents health domain types. For example: Weight Measurement represents a single weight measurement.


The HealthVault types browser lists all HealthVault data types (Thing types).

In the .NET SDK, the HealthRecordItem class represents a Thing.

See the following articles for more information about the HealthVault data model:

HealthVault global architecture

For more information about the HealthVault global architecture, see About global architecture in the MSDN Library.