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. Connecting an external account cannot be done using the REST API, since it requires the involvement of the participant.

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.

External Account Object

The basic external account data object is common to many of the external account APIs.

id int

Assigned identifier for this connected external account.

participantID guid

Internal, stable, unique ID for the participant associated with the account.

participantIdentifier string

Project-specific identifier for the participant associated with the account.

status string

Account status. See account status values.

provider object

The provider for this external account.

provider.id int

Assigned identifier for this provider.

provider.name string

Provider name.

provider.category string

The type of provider. One of: Provider, Health Plan or Device Manufacturer.

provider.logoUrl string

A URL to retreive the logo for this provider.

lastRefreshDate date

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

connectionDate date

Date (in UTC) when the account initially connected.

providerUserID string

The user ID used within the external provider’s system.

Sample External Account Data
{
   "id": 1234,
   "participantIdentifier": "ABC-123",
   "participantID": "063BCA09-3265-4AA9-B550-00010BC0B954",
   "status": "fetchComplete",
   "provider": {
       "id": 42,
       "name": "CareEvolution FHIR",
       "category": "Provider",
       "logoUrl": "https://mydatahelps.org/api/v1/delegated/externalaccountproviders/1/logo"
   },
   "lastRefreshDate": "2023-07-26T18:22:42.93",
   "connectionDate": "2020-10-01T04:18:52.01",
   "providerUserID": "A12345"
}
{ "id": 1234, "participantIdentifier": "ABC-123", "participantID": "063BCA09-3265-4AA9-B550-00010BC0B954", "status": "fetchComplete", "provider": { "id": 42, "name": "CareEvolution FHIR", "category": "Provider", "logoUrl": "https://mydatahelps.org/api/v1/delegated/externalaccountproviders/1/logo" }, "lastRefreshDate": "2023-07-26T18:22:42.93", "connectionDate": "2020-10-01T04:18:52.01", "providerUserID": "A12345" }

Query Connected External Accounts

GET api/v1/administration/projects/:projectID/externalAccounts

Query Parameters

participantID guid

Search for accounts based on the participant’s internal, stable, unique ID field.

participantIdentifier string

Search for accounts based on the project-set, unique participant identifier.

providerIDs string

A comma-separated list of provider IDs, obtained from a prior query.

providerCategories string

A comma-separated list of provider categories. Category may be one of: Provider, Health Plan or Device Manufacturer.

providerNames string

A comma-separated list of provider names, obtained from a prior query.

externalAccountStatuses string

A comma-separated list of account status codes. See account status values.

limit integer

How many entries to include in each page of results. Default and maximum is 100.

nextPageID guid

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that in this parameter to query the next page. When excluded, retrieves the first page.

Response Fields

externalAccounts collection

A list of the external accounts matching the query criteria.

externalAccounts.id int

Assigned identifier for this connected external account.

externalAccounts.participantID guid

Internal, stable, unique ID for the participant associated with the account.

externalAccounts.participantIdentifier string

Project-specific identifier for the participant associated with the account.

externalAccounts.status string

Account status. See account status values.

externalAccounts.provider object

The provider for this external account.

externalAccounts.provider.id int

Assigned identifier for this provider.

externalAccounts.provider.name string

Provider name.

externalAccounts.provider.category string

The type of provider. One of: Provider, Health Plan or Device Manufacturer.

externalAccounts.provider.logoUrl string

A URL to retreive the logo for this provider.

externalAccounts.lastRefreshDate date

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

externalAccounts.connectionDate date

Date (in UTC) when the account initially connected.

externalAccounts.providerUserID string

The user ID used within the external provider’s system.

nextPageID

Identifier that you can use to retrieve the next page of results.

Sample Response
{
   "externalAccounts": [
       {
           "id": 1234,
           "participantIdentifier": "ABC-123",
           "participantID": "063BCA09-3265-4AA9-B550-00010BC0B954",
           "status": "fetchComplete",
           ...
       }
   ],
   "nextPageID": "26519109-6f13-ed11-8be3-dcfb485e2b02"
}
{ "externalAccounts": [ { "id": 1234, "participantIdentifier": "ABC-123", "participantID": "063BCA09-3265-4AA9-B550-00010BC0B954", "status": "fetchComplete", ... } ], "nextPageID": "26519109-6f13-ed11-8be3-dcfb485e2b02" }
See External Account Object for all available fields.

Delete an External Account Connection

DELETE api/v1/administration/projects/:projectID/externalAccounts/:accountID

You can delete one of a participant’s external account connections. The :accountID segment references a specific account, matching the id field obtained from the Query Connected External Accounts operation.