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 Exports
Download Export
Get Institutions
Add/Update Institution
Delete Institution

Project Object

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

id guid

Unique project identifier.

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.

licensed boolean

Indicates whether the project has been licensed.

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.surveyID guid

Identifier for 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.

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.

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.

    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",
    "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:

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"
      },
      "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 - Spanish
zh-Hans - Simplified Chinese.

Get Projects

GET /api/v1/administration/projects/

Response Fields

projects collection

List of projects.

+ Child Fields

projects.id guid

Unique project identifier.

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.licensed boolean

Indicates whether the project has been licensed.

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.surveyID guid

Identifier for 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.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.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.

    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

Response Fields

id guid

Unique project identifier.

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.

licensed boolean

Indicates whether the project has been licensed.

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.surveyID guid

Identifier for 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.

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.

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.

    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/

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.surveyID guid

Identifier for 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.

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.

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.

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.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.licensed boolean

Indicates whether the project has been licensed.

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.surveyID guid

Identifier for 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.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.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.

    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

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.surveyID guid

Identifier for 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.

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.

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.

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.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.licensed boolean

Indicates whether the project has been licensed.

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.surveyID guid

Identifier for 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.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.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.

    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

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.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.licensed boolean

Indicates whether the project has been licensed.

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.surveyID guid

Identifier for 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.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.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.

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

pageNumber integer

If the exports span multiple pages, this is the page number to request (0 by default, 0-indexed).

pageSize integer

The number of exports to return per page.

Response Fields

pageNumber integer

The page number requested (0-indexed).

totalExports integer

How many exports are available in total.

exports collection

The individual data exports.

+ Child Fields

exports.ID guid

Unique identifier for this export.

exports.dataStartDate date

Starting date for the range of data included in the export, in ISO8601 format.

exports.dataEndDate date

Ending date for the range of data included in the export, in ISO8601 format.

exports.insertDate date

Date the export was created, in ISO8601 format.

exports.runStartDate date

Date the export started running, in ISO8601 format.

exports.runEndDate date

Date the export finished running, in ISO8601 format.

exports.status string

Status of the export, one of: queued, exporting, uploading, finished, failed, or suspended.

exports.errorMessage string

A user-readable error message if the export failed. Will be null if the export was successful.

exports.exportType string

The type of export, either incremental or onDemand.

    Sample Response 
    
  

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

Note
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

institutions array

+ 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

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