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.

Contents

Account Status
External Account Object
Query Connected External Accounts
Delete an External Account Connection

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.

status string

Account status. See account status values.

provider object

The provider for this external account.

Child Fields

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.

provider.enabled boolean

If the participant is not already connected to the provider, this indicates if they are able to connect.

provider.message string

If the provider is not enabled, this message explains why. It is suitable for display to the participant.

provider.relatedProvider string

If the provider is not enabled because there is already a connection through another provider, this is the name of that other provider.

provider.managingOrganization string

If the provider is not enabled, and it is managed through an organization, this is the name of that organization.

provider.successorID int

If the provider offers a newer/different connection that participants may want to migrate to (e.g., a new FHIR R4 endpoint replacing an old STU3 one), this is the id field of the successor 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.

dataScopes string

A space-delimited list specifying which types of data the participant has elected to share with MyDataHelps. Scope names are determined by the provider, and may include things like HEALTH_EXPORT (Garmin) or cardio_fitness (Fitbit). This is only available for providers in the “Device Manufacturer” category.

    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.

Child Fields

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.

Child Fields

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.provider.enabled boolean

If the participant is not already connected to the provider, this indicates if they are able to connect.

externalAccounts.provider.message string

If the provider is not enabled, this message explains why. It is suitable for display to the participant.

externalAccounts.provider.relatedProvider string

If the provider is not enabled because there is already a connection through another provider, this is the name of that other provider.

externalAccounts.provider.managingOrganization string

If the provider is not enabled, and it is managed through an organization, this is the name of that organization.

externalAccounts.provider.successorID int

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.

externalAccounts.dataScopes string

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.

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.