On-Demand Sync

Overview

On-Demand Sync lets you request a new medical account sync as needed. If the user has previously authorized access to their records and the authorization is current, issuing such a request triggers Human API to retrieve new data that have been made available at the source since the last synchronization.

There are two ways to perform an On-Demand Sync:

1. via API
2. via Connect

📘

How can I enable On-Demand Sync on my client app?

On-Demand sync is not enabled by default. If you would like to enable the feature, please contact your account manager at Human API.

Resync via API

To request a resync (i.e. on-demand sync), you can issue an “action” request for a specific user (identified by their humanId) and account (denoted by external account id).

You need to supply the accountId, which you can retrieve from the sources endpoint by performing the request GET https://api.humanapi.co/v1/human/sources for a user.

For example, by calling the /sources endpoint for a user, we may see a similar response as the following:

GET /v1/human/sources
Host: api.humanapi.co
Content-Type: application/json
Cache-Control: no-cache
Authorization: Bearer access-token

Response:
[
  {
    "id": "551ac6ef15eab1445e527c64",
    "source": "55a83bdc8d1eb1420aa1a71b",
    "sourceName": "Starfleet Medical",
    "connectedSince": "2018-07-20T21:07:13.136Z",
    "syncStatus": {
        "status": "ok",
        "details" : "ok",
        "synchedAt": "2018-07-20T21:07:13.136Z",
        "newestDate": "2018-04-20T19:06:11.151Z"
     }
  }
]

The "id" from the above response is the "accountId" needed to request a resync for this particular source.

Also, you will need the Client Token as Bearer for your Authorization.

The resync request will then resemble the following :

POST /api/v1/users/<humanId>/actions HTTP/1.1
Host: admin.humanapi.co
Content-Type: application/json
Cache-Control: no-cache
Authorization: Bearer your-client-token

Body:
{
  "action":"resync",
  "accountId":"551ac6ef15eab1445e527c64",
  
}

A successful request yields a response with 202 status code and an empty body.

The request will fail in the following cases :
- Post parameters are missing or incorrect (status 400)
- The user/account can’t be found or is disabled (status 404)
- Rate limit exceeded (status 429)

This operation is irreversible. Once you requested a resync and it’s acknowledged, you can’t abort it.

After a successful resync request, the user’s status will transition to a “Syncing” then transition to “Some Synced"/"All Synced” or an error state depending on the outcome of the sync operation.

Resync via Connect

Resync (i.e. on-demand sync) can also be performed by end users themselves via Connect. When the previously connected user opens the Human API Connect widget, they can request a resync by clicking the "RESYNC" button within the wallet.

📘

Missing "resync" button?

The button will only appear if On-Demand Sync is enabled for a clientapp. Please check in with your account manager if you would like to discuss its availability.

After clicking the "RESYNC" button, the data source will move to a "Syncing" status and the button will become temporarily unavailable until the process completes.

After a successful resync request, the user’s status will transition to a “Syncing” then transition to “Some Synced"/"All Synced” or an error state depending on the outcome of the sync operation.