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.
Contents
MyDataHelps.getExternalAccountProviders(search, category, pageSize, pageNumber)
Retrieves the list of external account providers supported by MyDataHelps.
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.
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.
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"
}
]
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.
The ID of the external account provider, available from the Retrieve External Account Providers API.
MyDataHelps.getExternalAccounts()
Resolves to a results
collection containing a list of connected external accounts.
Assigned identifier for this connected external account.
One of several possible statuses:
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.
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"
}
]
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
.
The ID for the external account to refresh, available from the Retrieve Connected External Accounts API.
A promise which resolves if the operation succeeded.
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");
} );
MyDataHelps.deleteExternalAccount(accountID)
The ID of the account to disconnect, available from the Retrieve Connected External Accounts API.
A promise which resolves if the operation succeeded.
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.");
} );