{"_id":"564d1afa4567342100ad96b8","__v":0,"category":{"_id":"564d1af94567342100ad96b1","version":"564d1af84567342100ad96aa","__v":1,"pages":["564d1afa4567342100ad96b7","564d1afa4567342100ad96b8","564d1afa4567342100ad96b9","564d1afa4567342100ad96ba"],"project":"551375e1d04af219007ddc52","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-28T19:56:44.186Z","from_sync":false,"order":6,"slug":"best-practices","title":"Best Practices"},"project":"551375e1d04af219007ddc52","version":{"_id":"564d1af84567342100ad96aa","project":"551375e1d04af219007ddc52","__v":1,"createdAt":"2015-11-19T00:42:32.705Z","releaseDate":"2015-11-19T00:42:32.705Z","categories":["564d1af94567342100ad96ab","564d1af94567342100ad96ac","564d1af94567342100ad96ad","564d1af94567342100ad96ae","564d1af94567342100ad96af","564d1af94567342100ad96b0","564d1af94567342100ad96b1","564d1af94567342100ad96b2"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.1.0","version":"1.1"},"user":"5539912a0074c80d00621b14","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-08-21T19:01:46.734Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Wellness Data\"\n}\n[/block]\nAfter 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.\n\n#Best Practices: Asynchronous Update Process\nIf you would like to update your UI to reflect a successful connection, the best thing to do is to query the [`/sources`](doc:source-sync-status) endpoint. The `source` and `supportedDataTypes` properties here will be available as soon as you have an `accessToken` for the user. \n\nYou can then rely on [Notifications](doc:notifications) to know when data is available to sync and use in your application. For the Wellness API, these should begin to appear within seconds of a successful authentication.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"When checking the `/sources` endpoint immediately after Connect finishes, the `devices` array may not yet be updated. It is updated on the first successful sync with the source.\"\n}\n[/block]\n\n# How long will it take for all data to be available?\nWe start synchronizing user data as soon as a user connects a source and selects \"Done\" in Connect. Specifically, we start pulling the most recent data from the source and work backward with a full **historical data sync** from there. As new data comes in, we will send you notifications to then sync that data for your users.\n\nAs a result, you can expect to receive recent data very 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](doc: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.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The speed at which a historical sync works is based on two things:\\n\\nA) Source Rate Limits\\nB) How much historical data the user has\\n\\n**Source Rate Limits** dictate the amount of data we can query per user in a given period of time from the specific source. We have negotiated higher rate limits for nearly all supported sources, so we can sync data as fast or faster than any other third party. However, as a result of the limits, full historical data cannot always be retrieved instantaneously.\\n\\nAdditionally, when limits do need to be accounted for our system smartly schedules data retrieval to maximize these source rate limits without compromising our ability to stay on track of new data for the specific user from that source.\\n\\nOverall, due to variations in data volume per user and rate limiting per source, there is no universal timeframe for a full historical sync, so it is best to rely on [Notifications](doc:notifications) so that you can retrieve the data as soon as possible.\",\n  \"title\": \"Historical Data Sync\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Medical Data\"\n}\n[/block]\nWe pull raw Medical Record data directly from healthcare providers, process and normalize the data, and then make it available via the [API endpoints](https://reference.humanapi.co/#medical-apis). 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.\n\n#Best Practices: Asynchronous Update Process\nDue to the time needed for retrieval and processing, after a user authenticates their medical records 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. \n\nSpecifically, once a user's historical data is available, we will send you a notification like the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[{\\n  \\\"humanId\\\": \\\"777e72a36b060995a551e1d9d4fa37fc\\\",\\n  \\\"updatedAt\\\": \\\"2015-08-28T05:13:45+00:00\\\",\\n  \\\"type\\\": \\\"externalaccount\\\",\\n  \\\"model\\\": \\\"externalaccount\\\",\\n  \\\"action\\\": \\\"updated\\\",\\n  \\\"objectId\\\": \\\"54cd4697a7b875300999ff44\\\",\\n  \\\"endpoint\\\": \\\"https://api.humanapi.co/v1/human/sources\\\"\\n}]\",\n      \"language\": \"json\",\n      \"name\": \"Notification\"\n    }\n  ]\n}\n[/block]\nIf 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"54cd4697a7b875300999ff44\\\",\\n  \\\"source\\\": \\\"emr-1-320\\\",\\n  \\\"connectedSince\\\": \\\"2015-01-31T21:18:15.672Z\\\",\\n  \\\"devices\\\": [\\n  \\t\\\"emr-1-320\\\"\\n  ],\\n  \\\"historySync\\\": {\\n  \\t\\\"status\\\": \\\"completed\\\"\\n  },\\n  \\\"sourceName\\\": \\\"Cleveland Clinic\\\",\\n  \\\"organization\\\": {\\n    \\\"id\\\": \\\"53c050ac51c69003200aa998\\\",\\n    \\\"name\\\": \\\"Cleveland Clinic\\\",\\n    \\\"href\\\": \\\"/medical/organizations/53c050ac51c69003200aa998\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Source Payload\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You should also check this endpoint and others you are working with as soon as you receive the user `accessToken`. In the event that the account data has been previously retrieved, the data will be immediately available.\",\n  \"title\": \"\"\n}\n[/block]\n# How long will it take for all data to be available?\nSimilar to the Wellness API, 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](doc:notifications) once it is fully processed and available for your application via the API.","excerpt":"","slug":"data-availability","type":"basic","title":"Data Availability & Design"}

Data Availability & Design


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. [block:api-header] { "type": "basic", "title": "Wellness Data" } [/block] 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. #Best Practices: Asynchronous Update Process If you would like to update your UI to reflect a successful connection, the best thing to do is to query the [`/sources`](doc:source-sync-status) endpoint. The `source` and `supportedDataTypes` properties here will be available as soon as you have an `accessToken` for the user. You can then rely on [Notifications](doc:notifications) to know when data is available to sync and use in your application. For the Wellness API, these should begin to appear within seconds of a successful authentication. [block:callout] { "type": "warning", "body": "When checking the `/sources` endpoint immediately after Connect finishes, the `devices` array may not yet be updated. It is updated on the first successful sync with the source." } [/block] # How long will it take for all data to be available? We start synchronizing user data as soon as a user connects a source and selects "Done" in Connect. Specifically, we start pulling the most recent data from the source and work backward with a full **historical data sync** from there. As new data comes in, we will send you notifications to then sync that data for your users. As a result, you can expect to receive recent data very 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](doc: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. [block:callout] { "type": "info", "body": "The speed at which a historical sync works is based on two things:\n\nA) Source Rate Limits\nB) How much historical data the user has\n\n**Source Rate Limits** dictate the amount of data we can query per user in a given period of time from the specific source. We have negotiated higher rate limits for nearly all supported sources, so we can sync data as fast or faster than any other third party. However, as a result of the limits, full historical data cannot always be retrieved instantaneously.\n\nAdditionally, when limits do need to be accounted for our system smartly schedules data retrieval to maximize these source rate limits without compromising our ability to stay on track of new data for the specific user from that source.\n\nOverall, due to variations in data volume per user and rate limiting per source, there is no universal timeframe for a full historical sync, so it is best to rely on [Notifications](doc:notifications) so that you can retrieve the data as soon as possible.", "title": "Historical Data Sync" } [/block] [block:api-header] { "type": "basic", "title": "Medical Data" } [/block] We pull raw Medical Record data directly from healthcare providers, process and normalize the data, and then make it available via the [API endpoints](https://reference.humanapi.co/#medical-apis). 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 Due to the time needed for retrieval and processing, after a user authenticates their medical records 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. Specifically, once a user's historical data is available, we will send you a notification like the following: [block:code] { "codes": [ { "code": "[{\n \"humanId\": \"777e72a36b060995a551e1d9d4fa37fc\",\n \"updatedAt\": \"2015-08-28T05:13:45+00:00\",\n \"type\": \"externalaccount\",\n \"model\": \"externalaccount\",\n \"action\": \"updated\",\n \"objectId\": \"54cd4697a7b875300999ff44\",\n \"endpoint\": \"https://api.humanapi.co/v1/human/sources\"\n}]", "language": "json", "name": "Notification" } ] } [/block] 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. [block:code] { "codes": [ { "code": "{\n \"id\": \"54cd4697a7b875300999ff44\",\n \"source\": \"emr-1-320\",\n \"connectedSince\": \"2015-01-31T21:18:15.672Z\",\n \"devices\": [\n \t\"emr-1-320\"\n ],\n \"historySync\": {\n \t\"status\": \"completed\"\n },\n \"sourceName\": \"Cleveland Clinic\",\n \"organization\": {\n \"id\": \"53c050ac51c69003200aa998\",\n \"name\": \"Cleveland Clinic\",\n \"href\": \"/medical/organizations/53c050ac51c69003200aa998\"\n }\n}", "language": "json", "name": "Source Payload" } ] } [/block] [block:callout] { "type": "info", "body": "You should also check this endpoint and others you are working with as soon as you receive the user `accessToken`. In the event that the account data has been previously retrieved, the data will be immediately available.", "title": "" } [/block] # How long will it take for all data to be available? Similar to the Wellness API, 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](doc:notifications) once it is fully processed and available for your application via the API.