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.

Account Status

The external account’s status reflects whether MyDataHelps was able to successfully retrieve data.

• unauthorized - The external account connection failed because MyDataHelps is not authorized to access the account. This can happen if the authorization has expired or the participant has revoked authorization.

• 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.

Get External Account Providers

MyDataHelps.getExternalAccountProviders(search, category, pageSize, pageNumber)

Retrieves the list of external account providers supported by MyDataHelps.

In addition to basic information about the provider, this method will indicate if the provider is enabled, which means the participant is allowed to add a connection to the provider. A provider may be disabled if an existing provider connection already grants access to the same data. This is usually the case for providers part of the same organization. The message field indicates why a provider is not available. For example: “You already have a connection to ProviderA through ProviderB (YourEHR).”

MyDataHelps.getExternalAccountProviders("careevolution", "provider")
	.then( function(result) {
		console.log(result);
	} );

{
  externalAccountProviders: [
    {
      "id": 1,
      "name": "CareEvolution FHIR",
      "category": "Provider",
      "logoUrl": "https://mydatahelps.org/api/v1/delegated/externalaccountproviders/1/logo"
    },
    ...
  ],
  totalExternalAccountProviders: 1719
}

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.

Retrieve Connected External Accounts

MyDataHelps.getExternalAccounts()

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"
  }
]

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.

var accountId = 5;

MyDataHelps.refreshExternalAccount(accountId)
	.then( function() {
		console.log("Successfully requested refresh");
	} );

Delete an External Account Connection

MyDataHelps.deleteExternalAccount(accountID)

var accountId = 5;

MyDataHelps.deleteExternalAccount(accountId)
	.then( function() {
		console.log("Successfully deleted the connected external account.");
	} );