The projects API allows you to create and manage your MyDataHelps projects.
Contents
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"
}
}
Several project settings can be localized for different languages, specifically:
displayName
displayDescription
learnMoreTitle
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 /api/v1/administration/projects/
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 /api/v1/administration/projects/:projectID
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",
...
}
POST /api/v1/administration/projects/
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.
Indicates the action performed: add
, update
, or delete
.
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,
...
}
...
}
PUT /api/v1/administration/projects/:projectID
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.
Indicates the action performed: add
, update
, or delete
.
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 /api/v1/administration/projects/:projectID
Indicates the action performed: add
, update
, or delete
.
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 /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.
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.
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"
},
...
]
}
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 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.