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.

Retrieve External Account Providers

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

Retrieves the list of external account providers supported by MyDataHelps.

Parameters

search string

Limit search results to account providers whose keyword, postal code, city, or state begins with the search string. Case-insensitive.

category string

Limit search results to account providers with a category exactly matching the search string. Case-insensitive.

pageSize integer

When provided, results will be paginated with the specified number of entries per page. The pageNumber parameter can be used to access individual pages.

pageNumber integer

When the pageSize parameter is specified, this parameter can be used to access specific pages of the paginated output. Defaults to page 1.

Returns

Promise<ExternalAccountProvider[]>

Resolves to a results collection containing a list of external account providers.

results[n].id int

Assigned identifier for this external account provider.

results[n].name string

Name of the external account provider.

results[n].category string

Type of account provider; one of “Provider”, “Health Plan” or “Device Manufacturer”.

results[n].logoUrl string

Full URL from which the logo can be retrieved. Undefined if no logo is available for the provider.

Availability

MyDataHelps Views
Web View Steps
Retrieving an External Account Provider
MyDataHelps.getExternalAccountProviders("careevolution", "provider")
	.then( function(result) {
		console.log(result);
	} );
MyDataHelps.getExternalAccountProviders("careevolution", "provider") .then( function(result) { console.log(result); } );
Console Output
[
  {
    "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

externalAccountProviderID int (required)

The ID of the external account provider, available from the Retrieve External Account Providers API.

Availability

MyDataHelps Views
Web View Steps

Retrieve Connected External Accounts

MyDataHelps.getExternalAccounts()

Returns

Promise<ExternalAccount[]>

Resolves to a results collection containing a list of connected external accounts.

results[n].id int

Assigned identifier for this connected external account.

results[n].status string

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.
results[n].provider ExternalAccountProvider

The provider for this external account.

results[n].provider.id int

Assigned identifier for this external account provider.

results[n].provider.name string

Name of the external account provider.

results[n].provider.category string

Type of account provider; one of “Provider”, “Health Plan” or “Device Manufacturer”.

results[n].provider.logoUrl string

Full URL from which the logo can be retrieved. Undefined if no logo is available for the provider.

results[n].lastRefreshDate date

Date (in UTC) when the account last successfully refreshed.

Availability

MyDataHelps Views
Web View Steps
Retrieving All Connected External Accounts
MyDataHelps.getExternalAccounts()
	.then( function(result) {
		console.log(result);
	} );
MyDataHelps.getExternalAccounts() .then( function(result) { console.log(result); } );
Console Output
[ 
  {
    "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

accountId int (required)

The ID for the external account to refresh, available from the Retrieve Connected External Accounts API.

Returns

Promise

A promise which resolves if the operation succeeded.

Availability

MyDataHelps Views
Web View Steps
Requesting the Refresh of an External Account
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

accountID int (required)

The ID of the account to disconnect, available from the Retrieve Connected External Accounts API.

Returns

Promise

A promise which resolves if the operation succeeded.

Availability

MyDataHelps Views
Web View Steps
Deleting an External Account
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."); } );