Patient Connect

Patient Connect is a way for an application to establish a connection with a user without requiring a patient-facing user interface. It is a good choice for apps that do not have a user interface and want to exchange data with users on an ongoing basis.

For example, a clinic may support syncing patient data with HealthVault, but it does not have a website that allows users to log in and connect via the online web user approach. The clinic can instead use Patient Connect to establish connections with users and then begin interacting with their HealthVault data. Until the connection is authorized by the user, the app can not read or write any of the user’s data.

Establishing the connection

A typical Patient Connect connection is made in the following way.

  1. A patient visits a clinic and wants to enable the clinic to exchange data with his HealthVault account.

  2. The clinic's app creates a connect request in HealthVault based on the patient’s ID in the clinic’s system, a friendly name for the patient, and a secret question and answer that will be used to verify the patient’s identity.

  3. HealthVault returns an identity code for the connect request.

  4. The app then sends the user an email containing the identity code and a link to HealthVault. The email does not include the secret question or answer. (Alternatively, the clinic could give the patient a print-out with the information.)

  5. Later, the patient goes to the URL provided by the clinic and enters the identity code.

  6. The patient is prompted for the answer to his secret question, and when he enters it correctly, this validates his identity.

  7. The patient selects the HealthVault record to use with the app and then authorizes it.

  8. The user receives confirmation that the app has been authorized. This includes the Patient Connect Success message that you configured in the Application Configuration Center.

  9. The app is now authorized to exchange data with the user’s record, but it doesn't know it yet. It finds out by periodically polling HealthVault for the list of connect requests that have been authorized since the last time it checked. In doing so, it retrieves the HealthVault IDs for the users and their records.

  10. The app discovers that the user has authorized the app, so it stores the HealthVault IDs for the user and record and begins exchanging data with the record.

Patient Connect properties



Identity code

The unique code generated by HealthVault that identifies the request.

Users begin the process of accepting connect requests by going to https:// shellhostname/redirect.aspx?target=CONNECT and entering their identity code manually into the website. You can also provide the identity code as a query string parameter so users don’t have to manually enter it themselves.

For example: https:// shellhostname/redirect.aspx?target=CONNECT&targetqs=packageid%3d JKYZ-QNMN-VHRX-ZGNR-GZNH. For more more information, see Shell Redirect Interface.

Friendly name

A friendly name that can be presented to the user after the user successfully answers the challenge question. The friendly name should be something that is recognizable and distinguishes one connect request from another so that the user may choose the expected record during application authorization.

For example, a mother of 2 children may want to name her connect requests after each child so she can distinguish one child's connect request from the other's.

Secret question

A challenge question posed to the user once the identity code has been successfully entered. We recommend that the question be personal and easy to answer in one word. An empty question is not allowed.

Secret answer

The secret answer provided by the user. The secret answer cannot be empty, and it is case-insensitive but whitespace-sensitive. The .NET SDK enforces that the answer be at least 6 characters long.

External ID

A unique identifier supplied by the app for identifying the connect request. Use this value to map the patient’s information in the app to the HealthVault record being authorized. For example, this could be the patient identifier used to store information in the app’s database.

Platform XML methods

See the HealthVault method browser for more information on each XML request.




Creates a connect request.


Updates the external ID for a connect request.


Returns connect requests that have been authorized for the calling app since a given time. This method will return the external ID, which the app should use to map the authorized request to the user in its own system.


Deletes a pending connect request.


The HealthVault .NET SDK contains classes and methods in the Microsoft.Health.PatientConnect namespace for creating and managing Patient Connect connect requests.

Managing Patient Connect connections

Once a connect request is validated, the app has a limited amount of time (currently 90 days) to retrieve it; after that the request is deleted from HealthVault. We recommend that apps make a GetAuthorizedConnectRequests request daily or weekly to ensure connect requests are not missed.

If the user doesn't pick up the connect request within a certain amount of time (currently four weeks), the request will expire and no longer be available. Or, if the user attempts and fails to answer the question correctly (currently after three chances), he will not be able to use the connect request code anymore. In either case, the user will have to contact the clinic to issue a new connect request. Only one connect request is allowed per external ID per app, so the app will need to delete the original request and then create a new one.

A connect request can be used multiple times until it is deleted from HealthVault. This is useful for the following scenarios:

  • The user deauthorizes the app and then wants to reauthorize it. The user ID and record ID values are preserved during reauthorization, so the app doesn't have to update its store.

  • The user wants to select a different record. The app will remain authorized to the original record as well as the new one. Your app needs to be able to handle this scenario.

Each time the connect request is picked up, the time window for the app to call GetAuthorizedConnectRequests is restarted. If the connect request has already been deleted, then the app will have to create a new connect request in order to support these scenarios.

If the app isn't able to (or you don’t want to) store the user’s HealthVault IDs, it can instead use the Alternate ID APIs to store the mapping in HealthVault. Whenever the app needs to interact with the user’s record, it can query HealthVault with its own user ID to retrieve the HealthVault IDs (person ID and record ID) to use in subsequent calls.

Application configuration

To use this way of connecting with HealthVault users, you must select the ConnectPackage methods when configuring your application in the HealthVault Application Configuration Center. This set of methods is not available for mobile apps.

You can also set a custom message for the user upon successfully authorizing the app:

Patient Connect Success Message

Workflow diagram

The following diagram represents a typical Patient Connect workflow:

Patient Connect workflow 

Code samples using the .NET SDK

The following example creates a connect request

private void CreateConnectRequest(
    string friendlyName,
    string secretQuestion,
    string secretAnswer,
    string patientId)
    // Create an offline connection
    OfflineWebApplicationConnection connection = new OfflineWebApplicationConnection(
        Guid.Empty /* offlinePersonId */);

    // Create the connect request
    string code = PatientConnection.Create(
        null/* callbackUrl -- not implemented */,

    // Email the URL and code to the user
    SendConnectRequestMail(patientId, code);

The following example retrieves authorized connect requests

private void GetAuthorizedRequests(DateTime validatedSince)
    // Create an offline connection
    OfflineWebApplicationConnection connection = new OfflineWebApplicationConnection(
    Guid.Empty /* offlinePersonId */);

    // Retrieve connections validated since validatedSince
    Collection<ValidatedPatientConnection> validatedConnections =
    PatientConnection.GetValidatedConnections(connection, validatedSince);

    // Update local store with HealthVault IDs
    foreach (ValidatedPatientConnection validatedConnection in validatedConnections)