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
Notification Data Object
Query Notification History
Bulk Send Notifications
- Selecting Contact Details
- Participant Fields

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.

id guid

Unique identifier for a notification delivery.

participantID guid

Internal ID for the participant receiving the notification.

participantIdentifier string

Project-specific identifier for the participant receiving the notification.

identifier string

The identifier (name) used for the notification in the MyDataHelps project configuration.

contentVersion int

An incremental tracker for versions of the notification content.

sentDate date

Date the notification was sent, in ISO8601 format.

type string

The type of notification (Email, Sms, Push).

content string

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.

recipients string

Supplemental information about the specific emails/phone numbers used in the notification.

    Sample Notification Data 
    
  

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

Tip
Either a participant or notification identifier is required.

Query Parameters

participantID guid

Search for notifications sent to a participant based on the participant’s internal ID field.

participantIdentifier string

Search for notifications sent to a participant based on the project-specific participant identifier.

notificationIdentifier string

Search for deliveries for a specific notification by its project-specific identifier/name.

type string

Search for notifications with a specific type: Email, Sms, Push.

statusCode string

Search for notifications with a specific delivery status. See Notification Status.

sentBefore date

Search for notifications sent before this date, in ISO8601 format.

sentAfter date

Search for notifications sent after this date, in ISO8601 format.

limit int

How many entries to include in each page of results. Default and maximum is 100.

pageID guid

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

notifications collection

A list of the notifications.

+ Element Fields

notifications[n].id guid

Unique identifier for a notification delivery.

notifications[n].participantID guid

Internal ID for the participant receiving the notification.

notifications[n].participantIdentifier string

Project-specific identifier for the participant receiving the notification.

notifications[n].identifier string

The identifier (name) used for the notification in the MyDataHelps project configuration.

notifications[n].contentVersion int

An incremental tracker for versions of the notification content.

notifications[n].sentDate date

Date the notification was sent, in ISO8601 format.

notifications[n].type string

The type of notification (Email, Sms, Push).

notifications[n].content string

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.

notifications[n].recipients string

Supplemental information about the specific emails/phone numbers used in the notification.

nextPageID guid

Identifier that you can use to retrieve the next page of results.

    Sample Response 
    
  

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

Participant Fields

Notifications can be customized using various dynamic participant 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!

Tip
Be sure the field name in the notificationFields parameter exactly matches what you used in the message.

Body Parameters

participantID guid

Internal ID for the participant receiving the notification.

participantIdentifier string

Project-specific participant identifier for the participant receiving the notification.

notificationIdentifier string

The identifier (name) used for the notification in the MyDataHelps project configuration.

targetCustomField string

The name of a custom field that contains contact information. See Selecting Contact Details.

version int

Specifies the version of the notification to send. If omitted, will use the current published version.

notificationFields object

Key/value pairs containing the data that will be substituted into the message content. See Dynamic Fields.’

Response Fields

notifications collection

Status and information about each of the notifications sent.

+ Element Fields

notifications[n].statusDetail string

Further status information.

notifications[n].statusCode string

Delivery status. See Notification Status.

notifications[n].notification collection

Status and information about each of the notifications sent.

+ Element Fields

notifications[n].notification[n].participantID guid

Internal ID for the participant receiving the notification.

notifications[n].notification[n].participantIdentifier string

Project-specific participant identifier for the participant receiving the notification.

notifications[n].notification[n].notificationIdentifier string

The identifier (name) used for the notification in the MyDataHelps project configuration.

notifications[n].notification[n].targetCustomField string

The name of a custom field that contains contact information. See Selecting Contact Details.

notifications[n].notification[n].version int

Specifies the version of the notification to send. If omitted, will use the current published version.

notifications[n].notification[n].notificationFields object

Key/value pairs containing the data that will be substituted into the message content. See Dynamic Fields.’

    Sample Body Parameters 
    
  

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

]

    Sample Response 
    
  

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