REST API
Resources
Projects API
The projects API allows you to create and manage your MyDataHelps projects.
Contents
Project Object
The basic project object is common to many of the project APIs.
Unique project identifier.
Internal project name. Cannot be changed after the project is created.
Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.
Indicates whether the project has been licensed.
Project name displayed to participants.
Description of the project displayed to participants.
Project settings related to enrollment.
Code used by participants to enroll in this project, if allowCodeEnrollment is true. This code may be entered manually, or embedded in a QR code.
Whether to allow participants to enroll using a code, including by scanning a QR code.
Whether a valid participant identifier (given to the participants in advance) is required for enrollment.
Whether to list the project in the public projects directory. Available to licensed projects only.
A list of platforms that participants may use. Options include: iOS, android, and web.
Identifier for the project consent survey.
Whether to allow survey completion via link.
Prefix added to auto-generated participant identifiers.
Contact email for project support displayed to participants.
Contact number for project support displayed to participants.
A URL where participants can learn more about the project.
Site name or title for the learnMoreLink URL.
Translated versions of participant-visible text, such as project name and description. See localization settings for details.
Project settings related to email invitations.
Controls which email participants get when they are invited to join the project. Options include: default (the default system email), none (you will send the email yourself), and notification (a custom notification specified by emailNotificationIdentifier).
Identifier for the notification sent to invited participants when the invitation mode is set to notification.
Project settings related to notifications.
The name that will show as the sender in the ‘from’ field for email-based notifications.
The email address that will be used when replying to email-based notifications.
{
"id": "1d878704-64e6-e811-816b-9e01d28da2ca",
"name": "Sleep Time Study",
"licensed": false,
"appLayoutDisabled": true,
"type": "Research Study",
"displayName": "General Hospital Sleep Study",
"displayDescription": "Cutting-edge sleep study.",
"enrollmentSettings": {
"code": "ABC123",
"allowCodeEnrollment": true,
"requireIdentifierValidation": false,
"showInSearch": false,
"platforms": [
"iOS",
"android",
"web"
],
"surveyID": "063c0905-446b-4cd5-aa9f-3da958fec94a"
},
"allowSurveyCompletionViaLink": true,
"participantIdentifierPrefix": "PPT",
"defaultProtectedParticipants": false,
"supportEmail": "testproject@example.com",
"supportPhone": "888-555-1234",
"learnMoreLink": "https://example.com",
"learnMoreTitle": "Learn More At Test Project HQ",
"localizations": {
"es": {
"learnMoreTitle": "Project HQ (Spanish Version)",
"displayName": "Test Project (Spanish Version)",
"displayDescription": "Cutting-edge... (Spanish Version)"
}
},
"emailInvitationSettings": {
"mode": "notification",
"emailNotificationIdentifier": "SLEEP-Invitation-Email"
},
"notificationSettings": {
"emailFromName": "General Hospital Sleep Stody",
"emailReplyToAddress": "testproject@example.com"
}
}{
"id": "1d878704-64e6-e811-816b-9e01d28da2ca",
"name": "Sleep Time Study",
"licensed": false,
"appLayoutDisabled": true,
"type": "Research Study",
"displayName": "General Hospital Sleep Study",
"displayDescription": "Cutting-edge sleep study.",
"enrollmentSettings": {
"code": "ABC123",
"allowCodeEnrollment": true,
"requireIdentifierValidation": false,
"showInSearch": false,
"platforms": [
"iOS",
"android",
"web"
],
"surveyID": "063c0905-446b-4cd5-aa9f-3da958fec94a"
},
"allowSurveyCompletionViaLink": true,
"participantIdentifierPrefix": "PPT",
"defaultProtectedParticipants": false,
"supportEmail": "testproject@example.com",
"supportPhone": "888-555-1234",
"learnMoreLink": "https://example.com",
"learnMoreTitle": "Learn More At Test Project HQ",
"localizations": {
"es": {
"learnMoreTitle": "Project HQ (Spanish Version)",
"displayName": "Test Project (Spanish Version)",
"displayDescription": "Cutting-edge... (Spanish Version)"
}
},
"emailInvitationSettings": {
"mode": "notification",
"emailNotificationIdentifier": "SLEEP-Invitation-Email"
},
"notificationSettings": {
"emailFromName": "General Hospital Sleep Stody",
"emailReplyToAddress": "testproject@example.com"
}
}
Localization Settings
Several project settings can be localized for different languages, specifically:
displayNamedisplayDescriptionlearnMoreTitle
The localizations field stores the localized versions of these strings, indexed by language code. The following example shows how you might specify localized versions of the project’s display name and description:
"localizations": {
"es": {
"displayName": "Spanish Project Name",
"displayDescription": "Spanish Project Description"
},
"zh-Hans": {
"displayName": "Chinese Project Name",
"displayDescription": "Chinese Project Description"
}
} "localizations": {
"es": {
"displayName": "Spanish Project Name",
"displayDescription": "Spanish Project Description"
},
"zh-Hans": {
"displayName": "Chinese Project Name",
"displayDescription": "Chinese Project Description"
}
}
If a localized version is not specified for a string, the default (English) version will be used.
Supported language codes include:
es- Spanishzh-Hans- Simplified Chinese.
Get Projects
GET /api/v1/administration/projects/
Response Fields
List of projects.
Unique project identifier.
Internal project name. Cannot be changed after the project is created.
Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.
Indicates whether the project has been licensed.
Project name displayed to participants.
Description of the project displayed to participants.
Project settings related to enrollment.
Code used by participants to enroll in this project, if allowCodeEnrollment is true. This code may be entered manually, or embedded in a QR code.
Whether to allow participants to enroll using a code, including by scanning a QR code.
Whether a valid participant identifier (given to the participants in advance) is required for enrollment.
Whether to list the project in the public projects directory. Available to licensed projects only.
A list of platforms that participants may use. Options include: iOS, android, and web.
Identifier for the project consent survey.
Whether to allow survey completion via link.
Prefix added to auto-generated participant identifiers.
Contact email for project support displayed to participants.
Contact number for project support displayed to participants.
A URL where participants can learn more about the project.
Site name or title for the learnMoreLink URL.
Translated versions of participant-visible text, such as project name and description. See localization settings for details.
Project settings related to email invitations.
Controls which email participants get when they are invited to join the project. Options include: default (the default system email), none (you will send the email yourself), and notification (a custom notification specified by emailNotificationIdentifier).
Identifier for the notification sent to invited participants when the invitation mode is set to notification.
Project settings related to notifications.
The name that will show as the sender in the ‘from’ field for email-based notifications.
The email address that will be used when replying to email-based notifications.
[
{
"id": "eebabb6e-3908-4a49-8379-97e50f92a971",
"name": "Sleep Study",
...
},
{
"id": "7d0d36cc-8597-4418-9beb-3e5a6af28922",
"name": "Nutrition Study",
...
}
][
{
"id": "eebabb6e-3908-4a49-8379-97e50f92a971",
"name": "Sleep Study",
...
},
{
"id": "7d0d36cc-8597-4418-9beb-3e5a6af28922",
"name": "Nutrition Study",
...
}
]
Get Project
GET /api/v1/administration/projects/:projectID
Response Fields
Unique project identifier.
Internal project name. Cannot be changed after the project is created.
Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.
Indicates whether the project has been licensed.
Project name displayed to participants.
Description of the project displayed to participants.
Project settings related to enrollment.
Code used by participants to enroll in this project, if allowCodeEnrollment is true. This code may be entered manually, or embedded in a QR code.
Whether to allow participants to enroll using a code, including by scanning a QR code.
Whether a valid participant identifier (given to the participants in advance) is required for enrollment.
Whether to list the project in the public projects directory. Available to licensed projects only.
A list of platforms that participants may use. Options include: iOS, android, and web.
Identifier for the project consent survey.
Whether to allow survey completion via link.
Prefix added to auto-generated participant identifiers.
Contact email for project support displayed to participants.
Contact number for project support displayed to participants.
A URL where participants can learn more about the project.
Site name or title for the learnMoreLink URL.
Translated versions of participant-visible text, such as project name and description. See localization settings for details.
Project settings related to email invitations.
Controls which email participants get when they are invited to join the project. Options include: default (the default system email), none (you will send the email yourself), and notification (a custom notification specified by emailNotificationIdentifier).
Identifier for the notification sent to invited participants when the invitation mode is set to notification.
Project settings related to notifications.
The name that will show as the sender in the ‘from’ field for email-based notifications.
The email address that will be used when replying to email-based notifications.
{
"id": "1d878704-64e6-e811-816b-9e01d28da2ca",
"name": "Sleep Time Study",
"type": "Research Study",
"displayName": "General Hospital Sleep Study",
...
}{
"id": "1d878704-64e6-e811-816b-9e01d28da2ca",
"name": "Sleep Time Study",
"type": "Research Study",
"displayName": "General Hospital Sleep Study",
...
}
Add Project
POST /api/v1/administration/projects/
Body Fields
Internal project name. Cannot be changed after the project is created.
Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.
Project name displayed to participants.
Description of the project displayed to participants.
Project settings related to enrollment.
Whether to allow participants to enroll using a code, including by scanning a QR code.
Whether a valid participant identifier (given to the participants in advance) is required for enrollment.
Whether to list the project in the public projects directory. Available to licensed projects only.
A list of platforms that participants may use. Options include: iOS, android, and web.
Identifier for the project consent survey.
Whether to allow survey completion via link.
Prefix added to auto-generated participant identifiers.
Contact email for project support displayed to participants.
Contact number for project support displayed to participants.
A URL where participants can learn more about the project.
Site name or title for the learnMoreLink URL.
Translated versions of participant-visible text, such as project name and description. See localization settings for details.
Project settings related to email invitations.
Controls which email participants get when they are invited to join the project. Options include: default (the default system email), none (you will send the email yourself), and notification (a custom notification specified by emailNotificationIdentifier).
Identifier for the notification sent to invited participants when the invitation mode is set to notification.
Project settings related to notifications.
The name that will show as the sender in the ‘from’ field for email-based notifications.
The email address that will be used when replying to email-based notifications.
Response Fields
Indicates the action performed: add, update, delete, or none.
The project data.
Unique project identifier.
Internal project name. Cannot be changed after the project is created.
Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.
Indicates whether the project has been licensed.
Project name displayed to participants.
Description of the project displayed to participants.
Project settings related to enrollment.
Code used by participants to enroll in this project, if allowCodeEnrollment is true. This code may be entered manually, or embedded in a QR code.
Whether to allow participants to enroll using a code, including by scanning a QR code.
Whether a valid participant identifier (given to the participants in advance) is required for enrollment.
Whether to list the project in the public projects directory. Available to licensed projects only.
A list of platforms that participants may use. Options include: iOS, android, and web.
Identifier for the project consent survey.
Whether to allow survey completion via link.
Prefix added to auto-generated participant identifiers.
Contact email for project support displayed to participants.
Contact number for project support displayed to participants.
A URL where participants can learn more about the project.
Site name or title for the learnMoreLink URL.
Translated versions of participant-visible text, such as project name and description. See localization settings for details.
Project settings related to email invitations.
Controls which email participants get when they are invited to join the project. Options include: default (the default system email), none (you will send the email yourself), and notification (a custom notification specified by emailNotificationIdentifier).
Identifier for the notification sent to invited participants when the invitation mode is set to notification.
Project settings related to notifications.
The name that will show as the sender in the ‘from’ field for email-based notifications.
The email address that will be used when replying to email-based notifications.
{
"name": "Sleep Study",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"allowCodeEnrollment": true
}
...
}{
"name": "Sleep Study",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"allowCodeEnrollment": true
}
...
}
{
"actionTaken": "add",
"result": {
"id": "5d9061e1-9807-4ea7-a2f9-f5c9ddeeb5bb",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"code": "AB123",
"allowCodeEnrollment": true,
...
}
...
}{
"actionTaken": "add",
"result": {
"id": "5d9061e1-9807-4ea7-a2f9-f5c9ddeeb5bb",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"code": "AB123",
"allowCodeEnrollment": true,
...
}
...
}
Update Project
PUT /api/v1/administration/projects/:projectID
Body Fields
Internal project name. Cannot be changed after the project is created.
Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.
Project name displayed to participants.
Description of the project displayed to participants.
Project settings related to enrollment.
Whether to allow participants to enroll using a code, including by scanning a QR code.
Whether a valid participant identifier (given to the participants in advance) is required for enrollment.
Whether to list the project in the public projects directory. Available to licensed projects only.
A list of platforms that participants may use. Options include: iOS, android, and web.
Identifier for the project consent survey.
Whether to allow survey completion via link.
Prefix added to auto-generated participant identifiers.
Contact email for project support displayed to participants.
Contact number for project support displayed to participants.
A URL where participants can learn more about the project.
Site name or title for the learnMoreLink URL.
Translated versions of participant-visible text, such as project name and description. See localization settings for details.
Project settings related to email invitations.
Controls which email participants get when they are invited to join the project. Options include: default (the default system email), none (you will send the email yourself), and notification (a custom notification specified by emailNotificationIdentifier).
Identifier for the notification sent to invited participants when the invitation mode is set to notification.
Project settings related to notifications.
The name that will show as the sender in the ‘from’ field for email-based notifications.
The email address that will be used when replying to email-based notifications.
Response Fields
Indicates the action performed: add, update, delete, or none.
The project data.
Unique project identifier.
Internal project name. Cannot be changed after the project is created.
Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.
Indicates whether the project has been licensed.
Project name displayed to participants.
Description of the project displayed to participants.
Project settings related to enrollment.
Code used by participants to enroll in this project, if allowCodeEnrollment is true. This code may be entered manually, or embedded in a QR code.
Whether to allow participants to enroll using a code, including by scanning a QR code.
Whether a valid participant identifier (given to the participants in advance) is required for enrollment.
Whether to list the project in the public projects directory. Available to licensed projects only.
A list of platforms that participants may use. Options include: iOS, android, and web.
Identifier for the project consent survey.
Whether to allow survey completion via link.
Prefix added to auto-generated participant identifiers.
Contact email for project support displayed to participants.
Contact number for project support displayed to participants.
A URL where participants can learn more about the project.
Site name or title for the learnMoreLink URL.
Translated versions of participant-visible text, such as project name and description. See localization settings for details.
Project settings related to email invitations.
Controls which email participants get when they are invited to join the project. Options include: default (the default system email), none (you will send the email yourself), and notification (a custom notification specified by emailNotificationIdentifier).
Identifier for the notification sent to invited participants when the invitation mode is set to notification.
Project settings related to notifications.
The name that will show as the sender in the ‘from’ field for email-based notifications.
The email address that will be used when replying to email-based notifications.
{
"name": "Sleep Study",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"allowCodeEnrollment": true
}
...
}{
"name": "Sleep Study",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"allowCodeEnrollment": true
}
...
}
{
"actionTaken": "update",
"result": {
"id": "5d9061e1-9807-4ea7-a2f9-f5c9ddeeb5bb",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"code": "AB123",
"allowCodeEnrollment": true,
...
}
...
}{
"actionTaken": "update",
"result": {
"id": "5d9061e1-9807-4ea7-a2f9-f5c9ddeeb5bb",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"code": "AB123",
"allowCodeEnrollment": true,
...
}
...
}
Delete Project
DELETE /api/v1/administration/projects/:projectID
Response Fields
Indicates the action performed: add, update, delete, or none.
The project data.
Unique project identifier.
Internal project name. Cannot be changed after the project is created.
Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.
Indicates whether the project has been licensed.
Project name displayed to participants.
Description of the project displayed to participants.
Project settings related to enrollment.
Code used by participants to enroll in this project, if allowCodeEnrollment is true. This code may be entered manually, or embedded in a QR code.
Whether to allow participants to enroll using a code, including by scanning a QR code.
Whether a valid participant identifier (given to the participants in advance) is required for enrollment.
Whether to list the project in the public projects directory. Available to licensed projects only.
A list of platforms that participants may use. Options include: iOS, android, and web.
Identifier for the project consent survey.
Whether to allow survey completion via link.
Prefix added to auto-generated participant identifiers.
Contact email for project support displayed to participants.
Contact number for project support displayed to participants.
A URL where participants can learn more about the project.
Site name or title for the learnMoreLink URL.
Translated versions of participant-visible text, such as project name and description. See localization settings for details.
Project settings related to email invitations.
Controls which email participants get when they are invited to join the project. Options include: default (the default system email), none (you will send the email yourself), and notification (a custom notification specified by emailNotificationIdentifier).
Identifier for the notification sent to invited participants when the invitation mode is set to notification.
Project settings related to notifications.
The name that will show as the sender in the ‘from’ field for email-based notifications.
The email address that will be used when replying to email-based notifications.
{
"actionTaken": "delete",
"result": {
"id": "5d9061e1-9807-4ea7-a2f9-f5c9ddeeb5bb",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"code": "AB123",
"allowCodeEnrollment": true,
...
}
...
}{
"actionTaken": "delete",
"result": {
"id": "5d9061e1-9807-4ea7-a2f9-f5c9ddeeb5bb",
"displayName": "General Hospital Sleep Study",
"supportEmail": "sleepstudy@example.com",
"enrollmentSettings": {
"code": "AB123",
"allowCodeEnrollment": true,
...
}
...
}
Get Exports
GET /api/v1/administration/projects/:projectID/exports
Gets a list of all data exports. This report includes not only completed exports, but also ones that have been queued, are in progress, failed, etc. This gives you a full picture of your exports, similar to what you would see in MyDataHelps Designer.
Query Parameters
If the exports span multiple pages, this is the page number to request (0 by default, 0-indexed).
The number of exports to return per page.
Response Fields
The page number requested (0-indexed).
How many exports are available in total.
The individual data exports.
Unique identifier for this export.
Starting date for the range of data included in the export, in ISO8601 format.
Ending date for the range of data included in the export, in ISO8601 format.
Date the export was created, in ISO8601 format.
Date the export started running, in ISO8601 format.
Date the export finished running, in ISO8601 format.
Status of the export, one of: queued, exporting, uploading, finished, failed, or suspended.
A user-readable error message if the export failed. Will be null if the export was successful.
The type of export, either incremental or onDemand.
{
"pageNumber": 0,
"totalExports": 5,
"exports": [
{
"id": "00629f26-3eb2-4223-9201-ef42e4ccdd32",
"dataStartDate": "2022-08-30T20:39:18.93+00:00",
"dataEndDate": "2022-09-19T00:00:00+00:00",
"insertedDate": "2022-09-19T17:56:11.183-04:00",
"status": "finished",
"errorMessage": null,
"runEndDate": "2022-09-19T17:57:12.923Z",
"runStartDate": "2022-09-19T17:56:11.693Z",
"exportType": "onDemand"
},
...
]
}{
"pageNumber": 0,
"totalExports": 5,
"exports": [
{
"id": "00629f26-3eb2-4223-9201-ef42e4ccdd32",
"dataStartDate": "2022-08-30T20:39:18.93+00:00",
"dataEndDate": "2022-09-19T00:00:00+00:00",
"insertedDate": "2022-09-19T17:56:11.183-04:00",
"status": "finished",
"errorMessage": null,
"runEndDate": "2022-09-19T17:57:12.923Z",
"runStartDate": "2022-09-19T17:56:11.693Z",
"exportType": "onDemand"
},
...
]
}
Download Export
GET /api/v1/administration/projects/:projectID/exports/:exportID/data
Downloads a specific export as a ZIP file.
The response’s Content-Disposition header will be set to attachment and include a recommended filename. For example: Content-Disposition: attachment; filename=RK.CareEvolution.Demo_20220830-20220916.zip
The file name is not guaranteed to be unique.
The ZIP file will contain each of the export files selected in the project settings. See the MyDataHelps export documentation for details on the file names and data formats.
You can only download successful exports. If the status of the requested export is anything other than finished, a 404-NotFound error response will result.
Get Institutions
GET /api/v1/administration/projects/:projectID/institutions
Gets a list of all institutions defined within a project.
Response Fields
An internal ID uniquely identifying the institution.
A unique project-assigned code for the institution.
Display name for the institution.
[
{
"id": "82a3006f-4073-4d0b-ad51-a1bce31cce78",
"code": "City",
"name": "City General"
},
{
"id": "fac4d6fc-5609-4607-a76e-4dd7359259a4",
"code": "County",
"name": "County General"
}
][
{
"id": "82a3006f-4073-4d0b-ad51-a1bce31cce78",
"code": "City",
"name": "City General"
},
{
"id": "fac4d6fc-5609-4607-a76e-4dd7359259a4",
"code": "County",
"name": "County General"
}
]
Add/Update Institution
POST /api/v1/administration/projects/:projectID/institutions
If the provided code matches an existing institution, the system will update that institution. Otherwise it will create a new one.
Body Data
A unique project-assigned code for the institution.
Display name for the institution.
Response Fields
Indicates the action performed: add, update, delete, or none.
The institution data.
An internal ID uniquely identifying the institution.
A unique project-assigned code for the institution.
Display name for the institution.
{
"code": "City",
"name": "City General"
}{
"code": "City",
"name": "City General"
}
Delete Institution
DELETE /api/v1/administration/projects/:projectID/institutions/:institutionID
Response Fields
Indicates the action performed: add, update, delete, or none.
The institution data.
An internal ID uniquely identifying the institution.
A unique project-assigned code for the institution.
Display name for the institution.
{
"actionTaken": "delete",
"result": {
"id": "754526e5-3c2c-ee11-aaca-0afb9334277d",
"code": "City",
"name": "City General"
}
}{
"actionTaken": "delete",
"result": {
"id": "754526e5-3c2c-ee11-aaca-0afb9334277d",
"code": "City",
"name": "City General"
}
}
