This page exists as a guideline on how to design the full authentication flow for your users based on when you can expect newly authenticated data to be available for each data type.

After a user connects a source, we will immediately start the process of querying their historical data from the source to make it available to your application. However, some consideration must be made for the time it takes to do so when designing the user flow in your system.

How long will it take for all data to be available?

We start synchronizing user data as soon as a user connects a source. We pull the most recent data from the source and work backward with a full historical data sync from there.

Usually you can expect to receive recent data soon after a user connects, but it is often best to communicate to your users that historical data will continue to come in and to check back later if they don't immediately see all of their information. See the Source Sync Status page for more information on querying the API about connected sources and the status of Human API data syncs with the external source.

We pull raw Medical Record data directly from healthcare providers, process and normalize the data, and then make it available via the API Reference. In addition, healthcare providers provide differing means of accessing patient medical data so some data takes longer to retrieve than others. As a result, we recommend implementing an asynchronous update process.

Best Practices: Asynchronous Update Process

After a user authenticates their medical records and due to the time needed for retrieval and processing, it is best to initially indicate the successful connection in your application and that their records are being retrieved. When the data is available, you can then follow up with a notification or email telling them when their records have been retrieved and can be viewed.

Once a user's historical data is available, we will send you a notification like the following:

[{
  "humanId": "777e72a36b060995a551e1d9d4fa37fc",
  "updatedAt": "2018-05-28T05:13:45+00:00",
  "type": "externalaccount",
  "model": "externalaccount",
  "action": "updated",
  "objectId": "54cd4697a7b875300999ff44",
  "endpoint": "https://api.humanapi.co/v1/human/sources"
}]

If you then query https://api.humanapi.co/v1/human/sources/<objectId> using this information, you will see a payload similar to the one below that will indicate via historySync.status whether or not the historical synchronization is complete.

{
  "id": "54cd4697a7b875300999ff44",
  "source": "54dc427aaa6b4cb7d6203061",
  "connectedSince": "2015-01-31T21:18:15.672Z",
  "devices": [
  	"54dc427aaa6b4cb7d6203061"
  ],
  "historySync": {
  	"status": "completed"
  },
  "sourceName": "Cleveland Clinic",
  "organization": {
    "id": "53c050ac51c69003200aa998",
    "name": "Cleveland Clinic",
    "href": "/medical/organizations/53c050ac51c69003200aa998"
  }
}

The value of historySync.status will become "completed" when Human API's data sync with the source is finished. This indicates that the user's complete historical records for the individual source can be queried.

How long will it take for all data to be available?

This depends largely on the capabilities of the source and the amount of medical data that the user has authenticated. We retrieve the information as fast as the particular source will allow and notify you of its availability via Notifications once it is fully processed and available for your application via the API.