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, stable, unique ID for the participant receiving the notification.

participantIdentifier string

Project-set, unique 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.

schedule

Contains details about the schedule that triggered the notification, if applicable. Will be null if the notification was not triggered by a schedule.

Child Fields

schedule.id guid

Unique identifier for the schedule.

schedule.name string

Schedule name.

schedule.category string

User-assigned category for the schedule (optional).

schedule.interval integer

How often the notification is delivered, based on the interval type. For example, if intervalType is Weeks and interval is 4, it means the notification repeats every 4 weeks. Will be null if the schedule does not repeat.

schedule.intervalType string

Units for interval. May be Days, Weeks, Months, or Years.

sourceUser object

For a notification initiated by a coordinator action, this will record the coordinator’s name and email. Will be null for scheduled notifications.

    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"
  ],
  "sourceUser": null,
  "schedule": {
      "id": "a843df73-07c2-45a3-9808-98745fafc766",
      "name": "Weekly Reminder",
      "category": "Phase 1",
      "interval": 1,
      "intervalType": "Week"
  }
},
  {
  "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"
  ],
  "sourceUser": null,
  "schedule": {
      "id": "a843df73-07c2-45a3-9808-98745fafc766",
      "name": "Weekly Reminder",
      "category": "Phase 1",
      "interval": 1,
      "intervalType": "Week"
  }
},

Query Notification History

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

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, stable, unique ID field.

participantIdentifier string

Search for notifications sent to a participant based on the project-set, unique 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 as pageID to query the next page. When excluded, retrieves the first page.

Response Fields

notifications collection

A list of the notifications.

Child Fields

notifications[n].id guid

Unique identifier for a notification delivery.

notifications[n].participantID guid

Internal, stable, unique ID for the participant receiving the notification.

notifications[n].participantIdentifier string

Project-set, unique 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.

notifications[n].schedule

Contains details about the schedule that triggered the notification, if applicable. Will be null if the notification was not triggered by a schedule.

Child Fields

notifications[n].schedule.id guid

Unique identifier for the schedule.

notifications[n].schedule.name string

Schedule name.

notifications[n].schedule.category string

User-assigned category for the schedule (optional).

notifications[n].schedule.interval integer

notifications[n].schedule.intervalType string

Units for interval. May be Days, Weeks, Months, or Years.

notifications[n].sourceUser object

For a notification initiated by a coordinator action, this will record the coordinator’s name and email. Will be null for scheduled notifications.

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

See Notification Object for all notification fields.

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, stable, unique ID for the participant receiving the notification.

participantIdentifier string

Project-set, unique 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, stable, unique ID for the participant receiving the notification.

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

Project-set, unique 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
      }
    }
  ]
}