External Accounts
Participants frequently have accounts with services external to MyDataHelps, such as their provider’s EHR, their health plan, or their wearable device manufacturer. For more information see External Accounts. The external accounts API gives you a way for participants to link MyDataHelps to their external account(s), and to manage that link once it’s been established.
When you use the API to connect an external account, MyDataHelps will initiate an OAuth connection to the external service so the participant can authorize MyDataHelps to retrieve data. Applications are in control of how they present this functionality, such as by creating a generic form for any new connection, or with a button which connects to a specific service that is associated with your project.
MyDataHelps periodically polls and persists data from connected external accounts. Removing a connected external account deletes all related data. Refreshes can be manually triggered using the operation documented below. On iOS and Android devices, refreshes can also be triggered using the externalAccountSyncComplete event.
It is not necessary for participants to connect to their Apple Health and Google Fit accounts as external providers. These accounts are connected using your project’s sensor data settings and the participant’s data sharing settings.
Contents
Retrieve External Account Providers
MyDataHelps.getExternalAccountProviders(search, category, pageSize, pageNumber)
Retrieves the list of external account providers supported by MyDataHelps.
Parameters
Limit search results to account providers whose keyword, postal code, city, or state begins with the search string. Case-insensitive.
Limit search results to account providers with a category exactly matching the search string. Case-insensitive.
Results will be paginated with the specified number of entries per page.
Access a specific page of the paginated output. Zero-indexed.
Returns
Resolves to a results collection containing a list of external account providers.
Assigned identifier for this external account provider.
Name of the external account provider.
Type of account provider; one of “Provider”, “Health Plan” or “Device Manufacturer”.
Full URL from which the logo can be retrieved. Undefined if no logo is available for the provider.
Availability
MyDataHelps.getExternalAccountProviders("careevolution", "provider")
.then( function(result) {
console.log(result);
} );MyDataHelps.getExternalAccountProviders("careevolution", "provider")
.then( function(result) {
console.log(result);
} );
[
{
"id": 1,
"name": "CareEvolution FHIR",
"category": "Provider",
"logoUrl": "https://mydatahelps.org/api/v1/delegated/externalaccountproviders/1/logo"
}
][
{
"id": 1,
"name": "CareEvolution FHIR",
"category": "Provider",
"logoUrl": "https://mydatahelps.org/api/v1/delegated/externalaccountproviders/1/logo"
}
]
Connect an External Account
MyDataHelps.connectExternalAccount(externalAccountProviderID)
This will initiate a secure OAuth connection to the specified external account provider, where the participant will be prompted to provide their credentials and authorize MyDataHelps to retrieve data from the account.
Parameters
The ID of the external account provider, available from the Retrieve External Account Providers API.
Availability
Retrieve Connected External Accounts
MyDataHelps.getExternalAccounts()
Returns
Resolves to a results collection containing a list of connected external accounts.
Assigned identifier for this connected external account.
One of several possible statuses:
- Unauthorized: The external account connection was attempted, but not yet authorized.
- FetchingData: The connected external account is in the process of fetching data.
- Error: An error occurred while fetching data.
- FetchComplete: The connected external account has successfully retrieved data.
The provider for this external account.
Assigned identifier for this external account provider.
Name of the external account provider.
Type of account provider; one of “Provider”, “Health Plan” or “Device Manufacturer”.
Full URL from which the logo can be retrieved. Undefined if no logo is available for the provider.
Date (in UTC) when the account last successfully refreshed.
Availability
MyDataHelps.getExternalAccounts()
.then( function(result) {
console.log(result);
} );MyDataHelps.getExternalAccounts()
.then( function(result) {
console.log(result);
} );
[
{
"id": 5,
"status": "fetchingData",
"provider":
{
"id": 1,
"name": "CareEvolution FHIR",
"category": "Provider",
"logoUrl": "https://mydatahelps.org/api/v1/delegated/externalaccountproviders/1/logo"
},
"lastRefreshDate": "2021-05-03T20:16:44.873Z"
}
][
{
"id": 5,
"status": "fetchingData",
"provider":
{
"id": 1,
"name": "CareEvolution FHIR",
"category": "Provider",
"logoUrl": "https://mydatahelps.org/api/v1/delegated/externalaccountproviders/1/logo"
},
"lastRefreshDate": "2021-05-03T20:16:44.873Z"
}
]
Request the Refresh of Data from a Connected External Account
MyDataHelps.refreshExternalAccount(accountId)
This will initiate an asynchronous data refresh from the specified external account. If you need to know when the refresh has completed, you can poll the getExternalAccounts API and wait for the status to change to fetchComplete.
Parameters
The ID for the external account to refresh, available from the Retrieve Connected External Accounts API.
Returns
A promise which resolves if the operation succeeded.
Availability
var accountId = 5;
MyDataHelps.refreshExternalAccount(accountId)
.then( function() {
console.log("Successfully requested refresh");
} );var accountId = 5;
MyDataHelps.refreshExternalAccount(accountId)
.then( function() {
console.log("Successfully requested refresh");
} );
Delete an External Account Connection
MyDataHelps.deleteExternalAccount(accountID)
Parameters
The ID of the account to disconnect, available from the Retrieve Connected External Accounts API.
Returns
A promise which resolves if the operation succeeded.
Availability
var accountId = 5;
MyDataHelps.deleteExternalAccount(accountId)
.then( function() {
console.log("Successfully deleted the connected external account.");
} );var accountId = 5;
MyDataHelps.deleteExternalAccount(accountId)
.then( function() {
console.log("Successfully deleted the connected external account.");
} );
