REST API
Resources
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
External Account Object
The basic external account data object is common to many of the external account APIs.
See Data Overview for more information about how external accounts are handled in MyDataHelps.
Assigned identifier for this connected external account.
Internal ID for the participant associated with the account.
Project-specific identifier for the participant associated with the account.
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.
The provider for this external account.
Assigned identifier for this provider.
Provider name.
The type of provider. One of: Provider, Health Plan or Device Manufacturer.
A URL to retreive the logo for this provider.
Date (in UTC) when the account last successfully refreshed.
Date (in UTC) when the account initially connected.
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
Search for accounts based on the participant’s internal ID field.
Search for accounts based on the project-specific participant identifier.
A comma-separated list of provider IDs, obtained from a prior query.
A comma-separated list of provider categories. Category may be one of: Provider, Health Plan or Device Manufacturer.
A comma-separated list of provider names, obtained from a prior query.
A comma-separated list of account status codes. Each status must be one of: Unauthorized, FetchingData, Error, or FetchComplete.
How many entries to include in each page of results. Default and maximum is 100.
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
A list of the external accounts matching the query criteria.
Assigned identifier for this connected external account.
Internal ID for the participant associated with the account.
Project-specific identifier for the participant associated with the account.
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.
The provider for this external account.
Assigned identifier for this provider.
Provider name.
The type of provider. One of: Provider, Health Plan or Device Manufacturer.
A URL to retreive the logo for this provider.
Date (in UTC) when the account last successfully refreshed.
Date (in UTC) when the account initially connected.
The user ID used within the external provider’s system.
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.
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.
