Continuous Sync

Overview

Continuous Sync is a Medical API feature that allows you to get data updates for your users on a recurring basis (e.g. monthly, weekly) without intervention. It is helpful for use cases where it is required to maintain an up-to-date picture of your users’ health and how they change over time. This differs from On-Demand Sync in that the latter allows developers or end users to initiate a new sync anytime.

📘

Is Continuous Sync or On-Demand Sync applicable to the Wellness API?

By default, all integrated Wellness sources support resyncing at no additional cost. This guide is meant to address recurring syncs for medical data sources.

📘

How can I enable Continuous Sync?

Continuous Sync for medical sources is not enabled by default. If you would like to enable the feature, please contact your account manager at Human API.

After Continuous Sync is enabled, what happens now?

You can expect additional notifications for user medical data updates assuming you are using our notifications feature.

Human API maintains a schedule to retrieve a user’s new data. This means that if a user already synced their data once with Human API, then generates more data at the source (e.g. a new hospital visit), we will attempt to retrieve that new data according to the set schedule. You should receive a notification as a result of the process.

To understand the structure of the notification and how best to respond to them, please visit our documentation.

What if I don’t have notifications enabled?

If your implementation does not use our notifications feature, there are other ways you can find out if new data is available.

Compare createdAt and syncStatus.synchedAt

Check the maximum (or newest) createdAt timestamp for any medical object belonging to the user already saved in your database, then compare this value to the syncStatus.synchedAt value from the sources endpoint.

A discrepancy between these values indicates that new medical data for the source may be available from our API. An appropriate query, then, would be similar to the following:

// example
curl -H 'Authorization: Bearer userAccessToken’ https://api.humanapi.co/v1/human/medical/vitals?created_since=20181021181119544Z
GET /v1/human/medical/vitals?created_since=20181021181119544Z HTTP/1.1
Host: api.humanapi.co
Authorization: Bearer userAccessToken
Cache-Control: no-cache

The example above queries for the user's vitals created since October 21, 2018. The endpoint value may be replaced with the datatypes you require and created_since value is replaced with the user’s newest createdAt timestamp in your records. This helps to filter and request only for new data that Human API gathered from the user’s authenticated source.

It is recommended, however, to use notifications when possible as that provides the most efficient method to know when new medical data is available for a user from a previously authenticated source.

Handling sync failures

Continuous syncs for a medical account may be temporarily or permanently suspended. Temporary suspension is oftentimes due to user authentication issues (e.g. when the user changes their credentials at the source or is locked out at the source).

Continuous syncs may also be suspended when Human API detects persistent issues at the source provider. These issues can include patient portal outages.

The continuous sync schedule will resume once the user resolves the issue at the source or when the user re-authenticates their provider in Connect. Users will see a message in Connect much like the image below.

A sample request for users to re-authenticateA sample request for users to re-authenticate

A sample request for users to re-authenticate

📘

Tip

If a sync fails and user action is required based on the response of the /sources endpoint, it is recommended to prompt users to launch Connect and re-authenticate their medical source at earliest opportunity (e.g. at the user's next login to your platform).

Sources that support Continuous Sync

While Human API has many medical connections in the network, it does not support continuous syncs for all sources. The feature's availability is largely dependent on the integration with the source. As such, it's recommended to check the /sources endpoint "resync" response property to determine the data source's capability.

Further reading