Stream API.

The Stream API lets an external system — a survey tool, a REDCap workflow, a script, or any HTTP client — trigger a push notification to study participants on demand. Instead of waiting for a scheduled send, you POST to the Samply notify endpoint and the notification fires immediately. This is the right tool for event-contingent designs where a notification should follow an event of interest rather than a clock time.

Endpoint

Content-Type must be application/json. No authentication header is used — authentication is handled by the per-study notify token in the request body.

Notify token

Each study has a notify token that authorises requests to the API. Tokens have an expiry date set by the study owner. Generate or regenerate a token from the Stream API tab inside your study dashboard. Regenerating immediately invalidates the previous token — update any scripts that use it.

Only the study owner can generate tokens. Collaborators (members) can see the current token and use it in requests, but cannot regenerate it.

Request body

Targeting

The combination of groupID and participantID controls who receives the notification:

The groupID + participantIDcombination is designed for social ESM designs: participant A's action triggers a notification to the rest of their group, excluding themselves.

URL placeholders

The url field supports the same %TOKEN% placeholders as scheduled notifications. Samply substitutes them per-participant before delivering the push:

Code example

const url = "https://samply.uni-konstanz.de/api/notify";
const data = {
  projectID: "<your-study-id>",
  token:     "<your-notify-token>",
  title:     "your-notification-title",
  message:   "your-notification-message",
  url:       "https://survey.example.com/?id=%SAMPLY_ID%&code=%PARTICIPANT_CODE%&group=%GROUP_CODE%&message=%MESSAGE_ID%",
  expireIn:  60,          // minutes before an undelivered notification is discarded
  groupID:       "<optional>",
  participantID: "<optional>",
};

async function sendNotification(url, data) {
  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(data),
  });
  return response;
}

sendNotification(url, data);

Use cases

Event-contingent ESM triggered from a survey tool

At the end of a Qualtrics survey, an end-of-survey JavaScript snippet POSTs to the notify endpoint with the participant's participantID. A follow-up survey notification arrives on their device within seconds of completing the first.

Social interaction designs

When participant A submits a report flagging a social interaction, your backend POSTs with groupID set to their group and participantID set to participant A. The rest of the group receives a notification; participant A does not.

Lab-triggered ambulatory phase

A lab system starts the ambulatory phase of a study by POSTing a notification to all participants (projectID only, no group or participant filter) the moment the lab session ends, regardless of clock time.

Feasibility and performance

Shevchenko & Reips (2025) validated the Stream API in a two-week ESM study where an RSS feed of news articles was fetched daily and processed by ChatGPT into three conditions — original, paraphrased, and misinformation — before being streamed to participants via the notify endpoint. Three notifications per day were delivered to 110 participants based on live external events, not a fixed schedule.

Key findings:

• 83% overall response rate — comparable to or better than conventional ESM studies of similar duration.
• Android 89% vs. iOS 77% — response rates differed by platform; report platform as a covariate in analyses.
• AI modifications maintained readability — only 1.2% of AI-modified items were rated non-readable; misinformation was successfully introduced (84% unfamiliarity vs. 73% baseline).
• Dropout was consistent with other ESM studies of comparable length, confirming that real-time streaming does not increase participant burden.

The study demonstrates that the Stream API is suitable for designs where notification content must be generated or selected at the moment of delivery — including news-perception research, social media studies, public opinion measurement, healthcare interventions, and environmental monitoring. An open-source server application implementing the pipeline is available on GitHub.

Responses