REST API
Resources
Notifications API
The notifications API allows you to send notifications to participants, and see a history of what notifications have been sent.
Contents
Notification Status
When using the API, it can be helpful to understand the various delivery status codes.
| Code | Description |
|---|---|
| Succeeded | The notification was successfully delivered. |
| Unsubscribed | The participant has unsubscribed from this type of notification. |
| MissingContactInfo | For an email or SMS notification, the participant is missing the necessary email or phone number. |
| NoRegisteredMobileDevice | For a push notification, the participant does not have a mobile device, or has not enabled push notifications. |
| PastNotificationEndDate | The participant is no longer participating in the project. |
| ServiceError | MyDataHelps encountered an unexpected error delivering the notification. |
Notification Data Object
The basic notification object represents an instance of a notification delivery–a specific notification sent to a specific participant.
Unique identifier for a notification delivery.
Internal ID for the participant receiving the notification. Either participantID or participantIdentifier is required.
Project-specific identifier for the participant receiving the notification. . Either participantID or participantIdentifier is required.
The identifier (name) used for the notification in the MyDataHelps project configuration.
An incremental tracker for versions of the notification content.
Date the notification was sent, in ISO8601 format.
The type of notification (Email, Sms, Push).
The notification contents, as a set of key-value pairs. Specific values will vary depending on notification type, and may include body, title, and subject.
Supplemental information about the specific emails/phone numbers used in the notification.
{
"id": "2f8e1047-ab7e-4e7b-95da-c04d29e45123",
"participantID": "d80fce9b-e61a-4250-a8bd-9e6dc75108ca",
"participantIdentifier": "PT-123",
"identifier": "SLEEP-Reminder-SMS",
"contentVersion": 2,
"sentDate": "2021-11-18T19:01:07.24+00:00",
"statusCode": "Succeeded",
"type": "Sms",
"content": {
"body": "Remember to get a good night's sleep!"
},
"recipients": [
"555-123-4567"
]
},{
"id": "2f8e1047-ab7e-4e7b-95da-c04d29e45123",
"participantID": "d80fce9b-e61a-4250-a8bd-9e6dc75108ca",
"participantIdentifier": "PT-123",
"identifier": "SLEEP-Reminder-SMS",
"contentVersion": 2,
"sentDate": "2021-11-18T19:01:07.24+00:00",
"statusCode": "Succeeded",
"type": "Sms",
"content": {
"body": "Remember to get a good night's sleep!"
},
"recipients": [
"555-123-4567"
]
},
Query Notification History
GET api/v1/administration/projects/{projectID}/notifications/history?participantIdentifier=P123&limit=10
You may only query notification history for one participant at a time, so either the participantId or participantIdentifier is required.
Query Parameters
Search for notifications sent to a participant based on the participant’s internal ID field.
Search for notifications sent to a participant based on the project-specific participant identifier.
Search for deliveries for a specific notification by its project-specific identifier/name.
Search for notifications with a specific type: Email, Sms, Push.
Search for notifications with a specific delivery status. See Notification Status.
Search for notifications sent before this date, in ISO8601 format.
Search for notifications sent after this date, in ISO8601 format.
How many entries to include in each page of results. Default and maximum is 100.
Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that to pageID to query the next page. When excluded, retrieves the first page.
Response Fields
A list of the notifications.
Unique identifier for a notification delivery.
Internal ID for the participant receiving the notification. Either participantID or participantIdentifier is required.
Project-specific identifier for the participant receiving the notification. . Either participantID or participantIdentifier is required.
The identifier (name) used for the notification in the MyDataHelps project configuration.
An incremental tracker for versions of the notification content.
Date the notification was sent, in ISO8601 format.
The type of notification (Email, Sms, Push).
The notification contents, as a set of key-value pairs. Specific values will vary depending on notification type, and may include body, title, and subject.
Supplemental information about the specific emails/phone numbers used in the notification.
Identifier that you can use to retrieve the next page of results.
{
"notifications": [
{
"id": "b2ba821a-d9d6-4580-9edd-2bfd4f550ee5",
"participantID": "d80fce9b-e61a-4250-a8bd-9e6dc75108ca",
"identifier": "SLEEP-HealthTip-Email",
...
},
{
"id": "c9a58768-252c-478b-bda5-b8683d54af27",
"participantID": "e85c0be6-5c8d-45ec-9ebf-090e9000db02",
"identifier": "SLEEP-Reminder-SMS",
...
},
...
],
"nextPageID": "25fad9ec-1fd6-4726-993c-4de71d5f6d0e"
}{
"notifications": [
{
"id": "b2ba821a-d9d6-4580-9edd-2bfd4f550ee5",
"participantID": "d80fce9b-e61a-4250-a8bd-9e6dc75108ca",
"identifier": "SLEEP-HealthTip-Email",
...
},
{
"id": "c9a58768-252c-478b-bda5-b8683d54af27",
"participantID": "e85c0be6-5c8d-45ec-9ebf-090e9000db02",
"identifier": "SLEEP-Reminder-SMS",
...
},
...
],
"nextPageID": "25fad9ec-1fd6-4726-993c-4de71d5f6d0e"
}
Bulk Send Notifications
POST api/v1/administration/projects/{projectID}/notifications
This API method allows you to send notifications to one or more participants. Either a participant ID or identifier is required for each participant.
Selecting Contact Details
By default, SMS and email notifications will be sent to the email or mobile phone number associated with the participant’s MyDataHelps account. Some projects use a custom field to store an alternate email or phone number. To use one of these alternate contacts, specify the custom field name in the targetCustomField parameter.
For example, if you have a custom field named “PreferredEmail”, you would specify:
"targetCustomField": "PreferredEmail"
Dynamic Fields
Notifications can be customized using various dynamic fields. MyDataHelps will automatically substitute demographic, identifier, and custom field values into your notifications.
When using the API to send notifications, you may include your own dynamic fields. When you create a notification, include the following placeholder text where you want the dynamic field to appear:
<% NotificationField.YourFieldName %>
You may have multiple dynamic fields with different names. The notificationFields parameter contains values for each of your dynamic fields. For example:
Notification Message:
Congratulations! You have earned
<% NotificationFields.CurrentPoints %>points this week!
API Call:
notificationFields: {
CurrentPoints: 10
}
Displayed As:
Congratulations! You have earned 10 points this week!
Be sure the field name in the
notificationFields parameter exactly matches what you used in the message.
Body Parameters
Internal ID for the participant receiving the notification.
Project-specific participant identifier for the participant receiving the notification.
The identifier (name) used for the notification in the MyDataHelps project configuration.
The name of a custom field that contains contact information. See Selecting Contact Details.
Specifies the version of the notification to send. If omitted, will use the current published version.
Key/value pairs containing the data that will be substituted into the message content. See Dynamic Fields.’
Response Fields
Status and information about each of the notifications sent.
Further status information.
Delivery status. See Notification Status.
Status and information about each of the notifications sent.
Internal ID for the participant receiving the notification.
Project-specific participant identifier for the participant receiving the notification.
The identifier (name) used for the notification in the MyDataHelps project configuration.
The name of a custom field that contains contact information. See Selecting Contact Details.
Specifies the version of the notification to send. If omitted, will use the current published version.
Key/value pairs containing the data that will be substituted into the message content. See Dynamic Fields.’
[
{
"participantIdentifier": "d80fce9b-e61a-4250-a8bd-9e6dc75108ca",
"notificationIdentifier": "SLEEP-HealthTip-Email",
"version": 0,
"notificationFields": {
"CurrentPoints": 10,
"TotalPoints": 150
}
},
{
"participantIdentifier": "e85c0be6-5c8d-45ec-9ebf-090e9000db02",
"notificationIdentifier": "SLEEP-HealthTip-Email",
"version": 0,
"notificationFields": {}
},
][
{
"participantIdentifier": "d80fce9b-e61a-4250-a8bd-9e6dc75108ca",
"notificationIdentifier": "SLEEP-HealthTip-Email",
"version": 0,
"notificationFields": {
"CurrentPoints": 10,
"TotalPoints": 150
}
},
{
"participantIdentifier": "e85c0be6-5c8d-45ec-9ebf-090e9000db02",
"notificationIdentifier": "SLEEP-HealthTip-Email",
"version": 0,
"notificationFields": {}
},
]
{
"notifications": [
{
"statusDetail": null,
"statusCode": "succeeded",
"notification": {
"participantIdentifier": "5a3d0a1e-f1ac-4af1-ac60-8ced0224ccac",
"notificationIdentifier": "SLEEP-HealthTip-Email",
"version": 0,
"targetCustomField": null,
"notificationFields": {
"CurrentPoints": 20,
"TotalPoints": 100
}
}
]
}{
"notifications": [
{
"statusDetail": null,
"statusCode": "succeeded",
"notification": {
"participantIdentifier": "5a3d0a1e-f1ac-4af1-ac60-8ced0224ccac",
"notificationIdentifier": "SLEEP-HealthTip-Email",
"version": 0,
"targetCustomField": null,
"notificationFields": {
"CurrentPoints": 20,
"TotalPoints": 100
}
}
]
}
