External Accounts

Participants frequently have accounts with services external to RKStudio, 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.

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

Retrieve External Account Providers

MyDataHelps.getExternalAccountProviders(search, category)

Retrieves the list of external account providers supported by RKStudio.

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.

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 Applications
Web View Steps
Example: Retrieving an External Account Provider
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"
  }
]

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 Applications
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 Applications
Web View Steps
Example: Retrieving All Connected External Accounts
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"
  }
]

Request the Refresh of Data from a Connected External Account

MyDataHelps.refreshExternalAccount(accountId)

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 Applications
Web View Steps
Example: Requesting the Refresh of a Connected External Account
var accountId = 5;

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

Delete an External Account

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 Applications
Web View Steps
Example: Deleting a Connected External Account
var accountId = 5;

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