Continuous Sync


Continuous Sync is a new feature that allows you to get health data updates for your users on a recurring basis. 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.


How can I enable Continuous Sync?

Continuous Sync is not enabled by default. If you would like to enable the new feature, please contact your account manager at Human API or reach out to [email protected].

After Continuous Sync is enabled, what happens now?

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

Human API maintains a 30 day 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 within 30 days. 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’
GET /v1/human/medical/vitals?created_since=20181021181119544Z HTTP/1.1
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-authenticate



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).

Further reading