Docs·Notifications
GET
/api/v1/spreelytics/notificationsList notifications
Returns the notifications the audience's rules wrote, newest first, a page at a time, with how many are unread. Notifications are kept until the audience is deleted.
Read and unread are shared by everyone in the workspace: one marked read by anyone, in the app or through the API, is read for all. Every role can call it, Viewer included.
Keys: an account key or an audience key. Getting started explains both kinds.
Parameters
| Prop | In | Type | Notes |
|---|---|---|---|
contactListId | query | string | The audience id, a UUID. With an audience key it must be that key's own audience. |
page? | query | number | Page number, starting at 0. Defaults to 0. |
pageSize? | query | number | How many per page, from 1 to 100. Defaults to 25. |
startDate? | query | string | Optional, sent together with endDate: a YYYY-MM-DD date or an ISO UTC time, included. Narrows items and total, not unread. |
endDate? | query | string | Optional: the end of the window. It must come after startDate, and sending only one of the two answers 400. |
Response
| Prop | Type | Notes |
|---|---|---|
items | NotificationDto[] | This page of notifications, newest first. |
total | number | How many notifications there are in the window, across all pages. |
unread | number | How many notifications are unread at any time. The window does not narrow it. |
Each item in items
| Prop | Type | Notes |
|---|---|---|
id | string | The notification id. |
ruleId | string | The rule that wrote it, or null once that rule is deleted. |
ruleName | string | The rule's name when the notification was written. It stays after the rule is renamed or deleted. |
title | string | The rule's name, or Preview: and the name for a preview. |
message | string | What happened, as one sentence, such as Paid $49.00 for Pro plan or Visited /pricing. |
payload | object | What the match carried, or null. Depending on the rule: eventName, path, country, sessionId and visitorId; a funnel's type ("funnel") and its steps; a revenue or goal rule's type with its payment kind or its goalId and goalName; by, who did it (name, country, city, browser, os, device, each null when unknown, and a null name for an anonymous visitor); and "test": true on a preview. |
readAt | string | When it was marked read, by anyone in the workspace, or null while it is unread. |
createdAt | string | When it was written, in ISO 8601. |
Request
curl 'https://app.spreelytics.com/api/v1/spreelytics/notifications?contactListId=…' \
-H 'Authorization: Bearer YOUR_API_KEY'
const url = new URL('https://app.spreelytics.com/api/v1/spreelytics/notifications');
url.searchParams.set('contactListId', '…');
const res = await fetch(url, {
headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const data = await res.json();
import requests
res = requests.get(
"https://app.spreelytics.com/api/v1/spreelytics/notifications",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"contactListId": "…"},
)
data = res.json()
Response
{
"items": [
{
"id": "string",
"ruleId": "string",
"ruleName": "string",
"title": "string",
"message": "string",
"payload": "string",
"readAt": "string",
"createdAt": "string"
}
],
"total": 0,
"unread": 0
}