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.
Tip
See
Data Overview for more information about how external accounts are handled in MyDataHelps.
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.
provider
object
The provider for this external account.
provider.id
int
Assigned identifier for this provider.
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.
{
"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
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
externalAccounts.provider
object
The provider for this external account.
externalAccounts.provider.id
int
Assigned identifier for this provider.
externalAccounts.provider.name
string
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.
{
"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"
}
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.
Note
You cannot delete an external account connection for a participant that signed up for a MyDataHelps account. They manage their own external accounts. This API method is only valid for participants created through the API.