Projects API

The projects API allows you to create and manage your MyDataHelps projects.

Contents

Project Object
- Localization Settings
Get Projects
Get Project
Add Project
Update Project
Delete Project
Get Institutions
Add/Update Institution
Delete Institution
Import Project Module
Exports

Project Object

The basic project object is common to many of the project APIs.

id guid

Unique project identifier.

licensed boolean

Indicates whether the project has been licensed.

name string

Internal project name. Cannot be changed after the project is created.

type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

displayName string

Project name displayed to participants.

displayDescription string

Description of the project displayed to participants.

enrollmentSettings object

Project settings related to enrollment.

Child Fields

enrollmentSettings.code string

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.

enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

enrollmentSettings.surveyName guid

Name of the project consent survey.

allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

supportEmail string

Contact email for project support displayed to participants.

alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

supportPhone string

Contact number for project support displayed to participants.

learnMoreLink string

A URL where participants can learn more about the project.

learnMoreTitle string

Site name or title for the learnMoreLink URL.

production boolean

Whether the project is in production mode.

institutionsEnabled boolean

Whether the project has enabled institutions.

localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

emailInvitationSettings object

Project settings related to email invitations.

Child Fields

emailInvitationSettings.mode string

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).

emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

notificationSettings object

Project settings related to notifications.

Child Fields

notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

sensorData object

Sensor data settings.

customFieldDefinitions object

Details about each of the project’s custom fields.

endOfProject object

End of project configuration settings.

appLayout object

Custom application tabs and styles.

participantDetail object

Participant tabs.

supportedLocales string[]

List of supported locales.

defaultLocale string

Default locale.

webhooks object

Configured webhooks.

surveySettings object

Project surveys settings and survey events.

featuredSegments string[]

List of featured segment names.

coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Sample Project Data

    {
    "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",
    "institutionsEnabled": true,
    "localizations": {
        "es": {
            "learnMoreTitle": "Project HQ (Spanish Version)",
            "displayName": "Test Project (Spanish Version)",
            "displayDescription": "Cutting-edge... (Spanish Version)"
        }
    },
    ...
}
  {
    "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",
    "institutionsEnabled": true,
    "localizations": {
        "es": {
            "learnMoreTitle": "Project HQ (Spanish Version)",
            "displayName": "Test Project (Spanish Version)",
            "displayDescription": "Cutting-edge... (Spanish Version)"
        }
    },
    ...
}

Localization Settings

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:

Sample Localizations Settings

      "localizations": {
      "es": {
        "displayName": "Spanish Project Name",
        "displayDescription": "Spanish Project Description"
      },
      "nl": {
        "displayName": "Dutch Project Name",
        "displayDescription": "Dutch Project Description"
      }
  }
    "localizations": {
      "es": {
        "displayName": "Spanish Project Name",
        "displayDescription": "Spanish Project Description"
      },
      "nl": {
        "displayName": "Dutch Project Name",
        "displayDescription": "Dutch Project Description"
      }
  }

If a localized version is not specified for a string, the default (English) version will be used. For a full list of available locales, see Configuring Your Project for Multiple Languages (Localization)

Get Projects

GET /api/v1/administration/projects/

Gets configuration settings for all projects associated with the workspace.

Response Fields

projects collection

List of projects.

Child Fields

projects.id guid

Unique project identifier.

projects.licensed boolean

Indicates whether the project has been licensed.

projects.name string

Internal project name. Cannot be changed after the project is created.

projects.type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

projects.displayName string

Project name displayed to participants.

projects.displayDescription string

Description of the project displayed to participants.

projects.enrollmentSettings object

Project settings related to enrollment.

Child Fields

projects.enrollmentSettings.code string

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.

projects.enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

projects.enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

projects.enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

projects.enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

projects.enrollmentSettings.surveyName guid

Name of the project consent survey.

projects.allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

projects.participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

projects.supportEmail string

Contact email for project support displayed to participants.

projects.alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

projects.supportPhone string

Contact number for project support displayed to participants.

projects.learnMoreLink string

A URL where participants can learn more about the project.

projects.learnMoreTitle string

Site name or title for the learnMoreLink URL.

projects.production boolean

Whether the project is in production mode.

projects.institutionsEnabled boolean

Whether the project has enabled institutions.

projects.localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

projects.emailInvitationSettings object

Project settings related to email invitations.

Child Fields

projects.emailInvitationSettings.mode string

projects.emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

projects.notificationSettings object

Project settings related to notifications.

Child Fields

projects.notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

projects.notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

projects.featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

projects.recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

projects.sensorData object

Sensor data settings.

projects.customFieldDefinitions object

Details about each of the project’s custom fields.

projects.endOfProject object

End of project configuration settings.

projects.appLayout object

Custom application tabs and styles.

projects.participantDetail object

Participant tabs.

projects.supportedLocales string[]

List of supported locales.

projects.defaultLocale string

Default locale.

projects.webhooks object

Configured webhooks.

projects.surveySettings object

Project surveys settings and survey events.

projects.featuredSegments string[]

List of featured segment names.

projects.coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Sample Response

    [
    {
        "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",
        ...
    
    }
]

See Project Object for all project fields.

Get Project

GET /api/v1/administration/projects/:projectID

Gets a project’s configuration settings.

Tip
You can optionally use the /projects/:projectID/full URL to get other data associated with the project, including the project’s surveys, notifications, segments, schedules, and institutions.

Response Fields

id guid

Unique project identifier.

licensed boolean

Indicates whether the project has been licensed.

name string

Internal project name. Cannot be changed after the project is created.

type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

displayName string

Project name displayed to participants.

displayDescription string

Description of the project displayed to participants.

enrollmentSettings object

Project settings related to enrollment.

Child Fields

enrollmentSettings.code string

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.

enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

enrollmentSettings.surveyName guid

Name of the project consent survey.

allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

supportEmail string

Contact email for project support displayed to participants.

alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

supportPhone string

Contact number for project support displayed to participants.

learnMoreLink string

A URL where participants can learn more about the project.

learnMoreTitle string

Site name or title for the learnMoreLink URL.

production boolean

Whether the project is in production mode.

institutionsEnabled boolean

Whether the project has enabled institutions.

localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

emailInvitationSettings object

Project settings related to email invitations.

Child Fields

emailInvitationSettings.mode string

emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

notificationSettings object

Project settings related to notifications.

Child Fields

notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

sensorData object

Sensor data settings.

customFieldDefinitions object

Details about each of the project’s custom fields.

endOfProject object

End of project configuration settings.

appLayout object

Custom application tabs and styles.

participantDetail object

Participant tabs.

supportedLocales string[]

List of supported locales.

defaultLocale string

Default locale.

webhooks object

Configured webhooks.

surveySettings object

Project surveys settings and survey events.

featuredSegments string[]

List of featured segment names.

coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Sample Response

    {
    "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",
    ...
}

See Project Object for all project fields.

Add Project

POST /api/v1/administration/projects/

Creates a project.

Tip
By default, this uses the basic project fields shown below. You can optionally include the full project details, typically obtained by using the Get Project operation with the “full” option. This is commonly used to migrate a full project—including its surveys, segments, notifications, etc.—from one workspace to another.

Body Fields

name string

Internal project name. Cannot be changed after the project is created.

type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

displayName string

Project name displayed to participants.

displayDescription string

Description of the project displayed to participants.

enrollmentSettings object

Project settings related to enrollment.

Child Fields

enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

enrollmentSettings.surveyName guid

Name of the project consent survey.

allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

supportEmail string

Contact email for project support displayed to participants.

alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

supportPhone string

Contact number for project support displayed to participants.

learnMoreLink string

A URL where participants can learn more about the project.

learnMoreTitle string

Site name or title for the learnMoreLink URL.

production boolean

Whether the project is in production mode.

institutionsEnabled boolean

Whether the project has enabled institutions.

localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

emailInvitationSettings object

Project settings related to email invitations.

Child Fields

emailInvitationSettings.mode string

emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

notificationSettings object

Project settings related to notifications.

Child Fields

notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

sensorData object

Sensor data settings.

customFieldDefinitions object

Details about each of the project’s custom fields.

endOfProject object

End of project configuration settings.

appLayout object

Custom application tabs and styles.

participantDetail object

Participant tabs.

supportedLocales string[]

List of supported locales.

defaultLocale string

Default locale.

webhooks object

Configured webhooks.

surveySettings object

Project surveys settings and survey events.

featuredSegments string[]

List of featured segment names.

coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Response Fields

actionTaken string

Indicates the action performed: add, update, delete, or none.

result object

The project data.

Child Fields

result.id guid

Unique project identifier.

result.licensed boolean

Indicates whether the project has been licensed.

result.name string

Internal project name. Cannot be changed after the project is created.

result.type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

result.displayName string

Project name displayed to participants.

result.displayDescription string

Description of the project displayed to participants.

result.enrollmentSettings object

Project settings related to enrollment.

Child Fields

result.enrollmentSettings.code string

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.

result.enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

result.enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

result.enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

result.enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

result.enrollmentSettings.surveyName guid

Name of the project consent survey.

result.allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

result.participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

result.supportEmail string

Contact email for project support displayed to participants.

result.alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

result.supportPhone string

Contact number for project support displayed to participants.

result.learnMoreLink string

A URL where participants can learn more about the project.

result.learnMoreTitle string

Site name or title for the learnMoreLink URL.

result.production boolean

Whether the project is in production mode.

result.institutionsEnabled boolean

Whether the project has enabled institutions.

result.localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

result.emailInvitationSettings object

Project settings related to email invitations.

Child Fields

result.emailInvitationSettings.mode string

result.emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

result.notificationSettings object

Project settings related to notifications.

Child Fields

result.notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

result.notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

result.featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

result.recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

result.sensorData object

Sensor data settings.

result.customFieldDefinitions object

Details about each of the project’s custom fields.

result.endOfProject object

End of project configuration settings.

result.appLayout object

Custom application tabs and styles.

result.participantDetail object

Participant tabs.

result.supportedLocales string[]

List of supported locales.

result.defaultLocale string

Default locale.

result.webhooks object

Configured webhooks.

result.surveySettings object

Project surveys settings and survey events.

result.featuredSegments string[]

List of featured segment names.

result.coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Sample Body Data

    {
    "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
    }
    ...
}

Sample Response

    {
    "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,
            ...
        }
        ...
}

See Project Object for all project fields.

Update Project

PUT /api/v1/administration/projects/:projectID

Updates project settings.

Note
You can update the production flag to promote a project from testing to production mode, but this action cannot be undone.

Body Fields

name string

Internal project name. Cannot be changed after the project is created.

type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

displayName string

Project name displayed to participants.

displayDescription string

Description of the project displayed to participants.

enrollmentSettings object

Project settings related to enrollment.

Child Fields

enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

enrollmentSettings.surveyName guid

Name of the project consent survey.

allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

supportEmail string

Contact email for project support displayed to participants.

alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

supportPhone string

Contact number for project support displayed to participants.

learnMoreLink string

A URL where participants can learn more about the project.

learnMoreTitle string

Site name or title for the learnMoreLink URL.

production boolean

Whether the project is in production mode.

institutionsEnabled boolean

Whether the project has enabled institutions.

localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

emailInvitationSettings object

Project settings related to email invitations.

Child Fields

emailInvitationSettings.mode string

emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

notificationSettings object

Project settings related to notifications.

Child Fields

notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

sensorData object

Sensor data settings.

customFieldDefinitions object

Details about each of the project’s custom fields.

endOfProject object

End of project configuration settings.

appLayout object

Custom application tabs and styles.

participantDetail object

Participant tabs.

supportedLocales string[]

List of supported locales.

defaultLocale string

Default locale.

webhooks object

Configured webhooks.

surveySettings object

Project surveys settings and survey events.

featuredSegments string[]

List of featured segment names.

coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Response Fields

actionTaken string

Indicates the action performed: add, update, delete, or none.

result object

The project data.

Child Fields

result.id guid

Unique project identifier.

result.licensed boolean

Indicates whether the project has been licensed.

result.name string

Internal project name. Cannot be changed after the project is created.

result.type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

result.displayName string

Project name displayed to participants.

result.displayDescription string

Description of the project displayed to participants.

result.enrollmentSettings object

Project settings related to enrollment.

Child Fields

result.enrollmentSettings.code string

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.

result.enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

result.enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

result.enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

result.enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

result.enrollmentSettings.surveyName guid

Name of the project consent survey.

result.allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

result.participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

result.supportEmail string

Contact email for project support displayed to participants.

result.alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

result.supportPhone string

Contact number for project support displayed to participants.

result.learnMoreLink string

A URL where participants can learn more about the project.

result.learnMoreTitle string

Site name or title for the learnMoreLink URL.

result.production boolean

Whether the project is in production mode.

result.institutionsEnabled boolean

Whether the project has enabled institutions.

result.localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

result.emailInvitationSettings object

Project settings related to email invitations.

Child Fields

result.emailInvitationSettings.mode string

result.emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

result.notificationSettings object

Project settings related to notifications.

Child Fields

result.notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

result.notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

result.featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

result.recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

result.sensorData object

Sensor data settings.

result.customFieldDefinitions object

Details about each of the project’s custom fields.

result.endOfProject object

End of project configuration settings.

result.appLayout object

Custom application tabs and styles.

result.participantDetail object

Participant tabs.

result.supportedLocales string[]

List of supported locales.

result.defaultLocale string

Default locale.

result.webhooks object

Configured webhooks.

result.surveySettings object

Project surveys settings and survey events.

result.featuredSegments string[]

List of featured segment names.

result.coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Sample Body Data

    {
    "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
    }
    ...
}

Sample Response

    {
    "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,
            ...
        }
        ...
}

See Project Object for all project fields.

Delete Project

DELETE /api/v1/administration/projects/:projectID

Deletes a project.

Warning
This cannot be undone!

Response Fields

actionTaken string

Indicates the action performed: add, update, delete, or none.

result object

The project data.

Child Fields

result.id guid

Unique project identifier.

result.licensed boolean

Indicates whether the project has been licensed.

result.name string

Internal project name. Cannot be changed after the project is created.

result.type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

result.displayName string

Project name displayed to participants.

result.displayDescription string

Description of the project displayed to participants.

result.enrollmentSettings object

Project settings related to enrollment.

Child Fields

result.enrollmentSettings.code string

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.

result.enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

result.enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

result.enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

result.enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

result.enrollmentSettings.surveyName guid

Name of the project consent survey.

result.allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

result.participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

result.supportEmail string

Contact email for project support displayed to participants.

result.alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

result.supportPhone string

Contact number for project support displayed to participants.

result.learnMoreLink string

A URL where participants can learn more about the project.

result.learnMoreTitle string

Site name or title for the learnMoreLink URL.

result.production boolean

Whether the project is in production mode.

result.institutionsEnabled boolean

Whether the project has enabled institutions.

result.localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

result.emailInvitationSettings object

Project settings related to email invitations.

Child Fields

result.emailInvitationSettings.mode string

result.emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

result.notificationSettings object

Project settings related to notifications.

Child Fields

result.notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

result.notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

result.featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

result.recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

result.sensorData object

Sensor data settings.

result.customFieldDefinitions object

Details about each of the project’s custom fields.

result.endOfProject object

End of project configuration settings.

result.appLayout object

Custom application tabs and styles.

result.participantDetail object

Participant tabs.

result.supportedLocales string[]

List of supported locales.

result.defaultLocale string

Default locale.

result.webhooks object

Configured webhooks.

result.surveySettings object

Project surveys settings and survey events.

result.featuredSegments string[]

List of featured segment names.

result.coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Sample Response

    {
    "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,
            ...
        }
        ...
}

See Project Object for all project fields.

Get Institutions

GET /api/v1/administration/projects/:projectID/institutions

Gets a list of all institutions defined within a project.

Response Fields

institutions collection

Child Fields

institutions.id guid

An internal ID uniquely identifying the institution.

institutions.code string

A unique project-assigned code for the institution.

institutions.name string

Display name for the institution.

Sample Response

    [
    {
        "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

code string

A unique project-assigned code for the institution.

name string

Display name for the institution.

Response Fields

actionTaken string

Indicates the action performed: add, update, delete, or none.

result object

The institution data.

Child Fields

result.id guid

An internal ID uniquely identifying the institution.

result.code string

A unique project-assigned code for the institution.

result.name string

Display name for the institution.

Sample Body Data

    {
    "code": "City",
    "name": "City General"
}
  {
    "code": "City",
    "name": "City General"
}

Delete Institution

DELETE /api/v1/administration/projects/:projectID/institutions/:institutionID

Deletes an institution associated with a project.

Warning
This cannot be undone!

Response Fields

actionTaken string

Indicates the action performed: add, update, delete, or none.

result object

The institution data.

Child Fields

result.id guid

An internal ID uniquely identifying the institution.

result.code string

A unique project-assigned code for the institution.

result.name string

Display name for the institution.

Sample Response

    {
    "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"
    }
}

Import Project Module

PUT /api/v1/administration/projects/:projectID/institutions/:institutionID

Imports part(s) of a project configuration, such as surveys, segments, or app layout. Typically you will obtain the data by using the Get Project operation with the “full” option, select only the modules you want to include, and apply those modules selectively to a different project.

Note
This import is only additive. It will not update existing surveys/notifications/etc., and will not touch any that are not referenced.

For example, assume you want to duplicate your segment setup from Project A to Project B. You would:

Use Get Project with the “full” option to download the full project details for Project A.
Trim the resulting JSON output so that only the segments section remains.
Use Import Project Module to import the segments to Project B.

Request Fields

surveys object

Project surveys.

notifications object

Workspace notifications.

segments object

Project segment definitions.

schedules object

Project schedules.

institutions object

Project institutions.

participantColumnLayouts object

Participant column layouts.

customFieldDefinitions object

Details about each of the project’s custom fields.

recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

sensorData object

Sensor data settings.

coordinatorSurveys object

Surveys that coordinators can use to add new participants to the project.

surveySettings object

Project surveys settings and survey events.

appLayout object

Custom application tabs and styles.

participantDetail object

Participant tabs.

webhooks object

Configured webhooks.

Response Fields

actionTaken string

Indicates the action performed: add, update, delete, or none.

result object

The project data.

Child Fields

result.id guid

Unique project identifier.

result.licensed boolean

Indicates whether the project has been licensed.

result.name string

Internal project name. Cannot be changed after the project is created.

result.type string

Project type, displayed to participants and used to filter search results. May be one of: Research Study, Wellness Program, or Clinical Program.

result.displayName string

Project name displayed to participants.

result.displayDescription string

Description of the project displayed to participants.

result.enrollmentSettings object

Project settings related to enrollment.

Child Fields

result.enrollmentSettings.code string

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.

result.enrollmentSettings.allowCodeEnrollment boolean

Whether to allow participants to enroll using a code, including by scanning a QR code.

result.enrollmentSettings.requireIdentifierValidation boolean

Whether a valid participant identifier (given to the participants in advance) is required for enrollment.

result.enrollmentSettings.showInSearch boolean

Whether to list the project in the public projects directory. Available to licensed projects only.

result.enrollmentSettings.platforms collection

A list of platforms that participants may use. Options include: iOS, android, and web.

result.enrollmentSettings.surveyName guid

Name of the project consent survey.

result.allowSurveyCompletionViaLink boolean

Whether to allow survey completion via link.

result.participantIdentifierPrefix string

Prefix added to auto-generated participant identifiers.

result.supportEmail string

Contact email for project support displayed to participants.

result.alertEmail string

An optional email address for receiving alerts from MyDataHelps about your project.

result.supportPhone string

Contact number for project support displayed to participants.

result.learnMoreLink string

A URL where participants can learn more about the project.

result.learnMoreTitle string

Site name or title for the learnMoreLink URL.

result.production boolean

Whether the project is in production mode.

result.institutionsEnabled boolean

Whether the project has enabled institutions.

result.localizations object

Translated versions of participant-visible text, such as project name and description. See localization settings for details.

result.emailInvitationSettings object

Project settings related to email invitations.

Child Fields

result.emailInvitationSettings.mode string

result.emailInvitationSettings.emailNotificationIdentifier string

Identifier for the notification sent to invited participants when the invitation mode is set to notification.

result.notificationSettings object

Project settings related to notifications.

Child Fields

result.notificationSettings.emailFromName string

The name that will show as the sender in the ‘from’ field for email-based notifications.

result.notificationSettings.emailReplyToAddress string

The email address that will be used when replying to email-based notifications.

result.featuredSegments string[]

List of featured segments in the MyDataHelps Designer participants view. If null, the system will feature a default set of segments.

result.recruitmentSurveys object

Surveys that can be used to recruit participants to the project.

result.sensorData object

Sensor data settings.

result.customFieldDefinitions object

Details about each of the project’s custom fields.

result.endOfProject object

End of project configuration settings.

result.appLayout object

Custom application tabs and styles.

result.participantDetail object

Participant tabs.

result.supportedLocales string[]

List of supported locales.

result.defaultLocale string

Default locale.

result.webhooks object

Configured webhooks.

result.surveySettings object

Project surveys settings and survey events.

result.featuredSegments string[]

List of featured segment names.

result.coordinatorIntakeSurveys object

Surveys that coordinators can use to add new participants to the project.

Exports

For project exports, see Exports API.