The notifications API allows you to send notifications to participants, and see a history of what notifications have been sent.
Contents
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. |
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"
]
},
GET api/v1/administration/projects/{projectID}/notifications/history?participantIdentifier=P123&limit=10
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.
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"
}
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.
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"
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!
notificationFields
parameter exactly matches what you used in the message.
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.’
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
}
}
]
}