---
title: "POST /api/public/notifications/bulk"
method: POST
path: "/api/public/notifications/bulk"
tags: ["Notifications"]
---

# POST /api/public/notifications/bulk

`POST /api/public/notifications/bulk`

Send the same in-app notification to up to 100 trainees, immediately or on a schedule. Requires the notifications:send scope, which is separate from messaging:send (WhatsApp). Trainees this key may not reach are returned in skipped, and trainees over the 10-per-day cap in rateLimited; both are excluded from the send, and a 429 is returned only when no recipient remains. High-risk — send an Idempotency-Key so a retry cannot double-notify.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `traineeIds` string[], required — Between 1 and 100 trainee ids
  - `title` string, required — Short notification title
  - `message` string, required — Body text
  - `type` 'push' | 'popup' | 'both' — Delivery style. "push" (default) is a standard push notification, "popup" shows an in-app popup card, "both" sends a push and shows the popup. Never sends WhatsApp.
  - `popupData` object — Content of the in-app popup card. Only used when type is "popup" or "both".
    - `title` string
    - `description` string
    - `videoLink` string
    - `actionLink` string — URL opened when the call-to-action button is pressed
    - `buttonText` string — Call-to-action button label
    - `imageUrl` string
    - `dismissible` boolean — Whether the trainee can dismiss the popup. Defaults to true.
  - `scheduledAt` string — Shorthand for a single future delivery: an ISO date-time. Use schedule instead for recurring sends. Cannot be combined with schedule.
  - `schedule` object — Deliver later, optionally repeating. Omit both schedule and scheduledAt to send immediately. Cannot be combined with scheduledAt.
    - `startDate` string, required — First send date, ISO-8601. Either a date ("2026-06-15") or a full date-time.
    - `timeOfDay` string, required — Local time of day in 24h "HH:mm" format, e.g. "09:30"
    - `frequency` 'once' | 'daily' | 'weekly' | 'biweekly' | 'triweekly' | 'monthly' — Defaults to "once" (a single future send). Any other value repeats until endDate.
    - `weeklyDays` number[] — 0=Sunday..6=Saturday. Required for weekly, biweekly and triweekly.
    - `monthlyMode` 'byDate' | 'byWeekday' — For monthly: byDate uses monthlyDays, byWeekday uses monthlyWeekday plus monthlyWeekOfMonth. Defaults to byDate.
    - `monthlyDays` number[] — Days of the month for monthly byDate
    - `monthlyWeekday` number — 0=Sunday..6=Saturday for monthly byWeekday
    - `monthlyWeekOfMonth` 1 | 2 | 3 | 4 | -1 — 1-4, or -1 for the last week of the month
    - `endDate` string — Optional ISO date that stops a recurring schedule
    - `timezone` string — IANA timezone. Defaults to Asia/Jerusalem.

## Response `201`

Created

- object — Created
  - `data` object
    - `id` string, nullable
    - `type` 'push' | 'popup' | 'both'
    - `status` 'sent' | 'scheduled'
    - `recipients` number — How many trainees the notification was delivered to
    - `scheduledFor` string, nullable — ISO date-time of the first delivery when scheduled
    - `skipped` string[] — Trainee ids the key may not reach. They were left out of the send.
    - `skippedCount` number
    - `rateLimited` string[] — Trainee ids that already hit their daily notification cap. They were left out of the send.
    - `rateLimitedCount` number
  - `warnings` object[] — Non-fatal problems with follow-up writes. The resource was created, but each listed field was not applied.
    - `field` string
    - `message` string

## Other responses

- `400` — Default Response
- `401` — Default Response
- `403` — Default Response
- `404` — Default Response
- `409` — Default Response
- `429` — Default Response
- `500` — Default Response

---

[API](https://skmtc.dev/coach-platform/apis/coach-platform-api.md) · [All operations](https://skmtc.dev/coach-platform/apis/coach-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/coach-platform/coach-platform-api/revisions/3d18b514ae8c/schema)