> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/engineering-reference/api/notifications.md).

# Notifications API

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/api/notifications.md).
{% endhint %}

Push notifications and reminders, device tokens, notification settings and mutes, marketing popups, and in-app surveys.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `apipy` at `https://z2.snapfix.com`. php-apis, authpy and py\_scheduler call some of the apipy routes ([Push delivery](#push-delivery)).
* **Auth:** api\_php\_live\_v2: user token (authpy JWT in `Authorization: Bearer`). The mute routes change only the caller's own membership; the popups route checks only that the site exists. php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). No action here reads a `user_uuid` from the body: `get_mkt_popup` reads only the site, the survey and NPS actions take the user from the token payload, whose signature only the dispatcher checks, and the generic table actions check no user at all. apipy: user token (authpy JWT) on the device-token routes, `/req-to-notify-user`, `/req-to-notify-user-v1`, `/user-devices` and `/user-notification-settings`. Only `POST /fbu_devicetoken` and `/user-notification-settings` tie the request to the caller; the other device-token routes take any user or group ID, and the two `/req-to-notify-user` routes take their receivers and text from the caller. The other push and reminder routes need no login.
* **Used by:** web\_app\_v2 (the group list's bell, marketing popups on the Fix page, task reminder pushes), iOS and Android (device tokens, notification settings, marketing popups, task and group pushes), php-apis (sign-up, invitation and queue pushes), authpy (QR form and invitation pushes), py\_scheduler (task, due-date and planner reminders); 30 of the 45 endpoints have no known caller.
* **Answers and errors:** the api\_php\_live\_v2 envelope and the codes every `/v1/app` route can return are in [Tasks: common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors). php-apis and apipy answer HTTP `200` with `result` `false` and the message for their own errors ([Responses](https://docs.snapfix.com/engineering-reference/api.md#responses)). Each section lists its own errors.
* **Logs:** every apipy push writes a [`tPri_Log_NotifAPIRequests`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_notifapirequests.md) row with the whole request, its text and receivers included, and the FCM answers. The Laravel chat push route writes to the same table ([Chat](https://docs.snapfix.com/engineering-reference/api/chat.md#post-v1appnotificationsend)).

| Method | Path                                                                                      | Service            | Purpose                                                                                                                |
| ------ | ----------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| PUT    | [`/v1/app/notification/{businessUuid}/mute`](#put-v1appnotificationbusinessuuidmute)      | api\_php\_live\_v2 | Mute a group's notifications: sets `notifMute` to 1 on the caller's membership. The web's bell sends it after "Mute"   |
| PUT    | [`/v1/app/notification/{businessUuid}/unmute`](#put-v1appnotificationbusinessuuidunmute)  | api\_php\_live\_v2 | Unmute a group's notifications: sets `notifMute` to 0. The web's bell sends it at once                                 |
| GET    | [`/v1/app/parents/{uuid}/popups`](#get-v1appparentsuuidpopups)                            | api\_php\_live\_v2 | Get a site's active marketing popups                                                                                   |
| GET    | `/v1/app/user/survey`                                                                     | api\_php\_live\_v2 | Check the user's survey status (no caller)                                                                             |
| POST   | `/v1/app/user/survey`                                                                     | api\_php\_live\_v2 | Save the user's survey answer, a "remind me later" or a dismissal (no caller)                                          |
| ANY    | `?action=create_pri_notif_repeat_type`                                                    | php-apis           | Create notification repeat types, generic table action (no caller)                                                     |
| ANY    | `?action=create_pri_notification_business`                                                | php-apis           | Create group notification rows, generic table action (no caller)                                                       |
| ANY    | `?action=create_pub_notification_global`                                                  | php-apis           | Create global notification rows, generic table action (no caller)                                                      |
| ANY    | `?action=delete_pri_notif_repeat_type`                                                    | php-apis           | Delete notification repeat types, generic table action (no caller)                                                     |
| ANY    | `?action=delete_pri_notification_business`                                                | php-apis           | Delete group notification rows, generic table action (no caller)                                                       |
| ANY    | `?action=delete_pub_notification_global`                                                  | php-apis           | Delete global notification rows, generic table action (no caller)                                                      |
| POST   | [`?action=get_mkt_popup`](#post-actionget_mkt_popup)                                      | php-apis           | Get a site's active marketing popups, for the apps                                                                     |
| ANY    | `?action=modify_pri_notif_repeat_type`                                                    | php-apis           | Change notification repeat types, generic table action (no caller)                                                     |
| ANY    | `?action=modify_pri_notification_business`                                                | php-apis           | Change group notification rows, generic table action (no caller)                                                       |
| ANY    | `?action=modify_pub_notification_global`                                                  | php-apis           | Change global notification rows, generic table action (no caller)                                                      |
| ANY    | `?action=nps_check`                                                                       | php-apis           | Check the user's NPS survey status (no caller)                                                                         |
| ANY    | `?action=nps_feedback`                                                                    | php-apis           | Save NPS survey feedback (no caller)                                                                                   |
| ANY    | `?action=read_pri_notif_repeat_type`                                                      | php-apis           | Read notification repeat types by UUID, generic table action (no caller)                                               |
| ANY    | `?action=read_pri_notification_business`                                                  | php-apis           | Read group notification rows by UUID, generic table action (no caller)                                                 |
| ANY    | `?action=read_pub_notification_global`                                                    | php-apis           | Read global notification rows by UUID, generic table action (no caller)                                                |
| ANY    | `?action=save_pri_notif_repeat_type`                                                      | php-apis           | Save notification repeat types, generic table action (no caller)                                                       |
| ANY    | `?action=save_pri_notification_business`                                                  | php-apis           | Save group notification rows, generic table action (no caller)                                                         |
| ANY    | `?action=save_pub_notification_global`                                                    | php-apis           | Save global notification rows, generic table action (no caller)                                                        |
| ANY    | `?action=survey_check`                                                                    | php-apis           | Check the user's survey status (no caller)                                                                             |
| ANY    | `?action=survey_feedback`                                                                 | php-apis           | Save survey feedback (no caller)                                                                                       |
| POST   | `/fbb_devicetoken`                                                                        | apipy              | Save a group device token (no caller)                                                                                  |
| GET    | `/fbb_devicetoken/{uuid}`                                                                 | apipy              | Get a group device token (no caller)                                                                                   |
| GET    | `/fbb_devicetokens/{uuid_tBusiness}`                                                      | apipy              | List a group's device tokens (no caller)                                                                               |
| POST   | [`/fbu_devicetoken`](#post-fbu_devicetoken)                                               | apipy              | Save a user's device token and notification settings                                                                   |
| GET    | `/fbu_devicetoken/{uuid}`                                                                 | apipy              | Get a user device token (no caller)                                                                                    |
| GET    | `/fbu_devicetokens/{uuid_tUser}`                                                          | apipy              | List a user's device tokens (no caller)                                                                                |
| POST   | [`/job/due-reminder-notification`](#post-jobdue-reminder-notification)                    | apipy              | Send a task's due-date push and chat line                                                                              |
| POST   | `/job/reminder-notification`                                                              | apipy              | Send task reminder notifications, first version (no caller)                                                            |
| POST   | `/job/reminder-notification-debug`                                                        | apipy              | Send task reminder notifications, debug version without the 20-hour limit (no caller)                                  |
| POST   | [`/job/reminder-notification-v2`](#post-jobreminder-notification-v2)                      | apipy              | Send a task's reminder push and chat line (v2)                                                                         |
| POST   | [`/req-to-notify-group-admin`](#post-req-to-notify-group-admin)                           | apipy              | Notify a group's admins                                                                                                |
| POST   | [`/req-to-notify-site-admin`](#post-req-to-notify-site-admin)                             | apipy              | Notify a site's admins                                                                                                 |
| POST   | [`/req-to-notify-user`](#post-req-to-notify-user)                                         | apipy              | Send push notifications to users. The receivers and the text come from the caller, and nothing ties them to the caller |
| POST   | [`/req-to-notify-user-for-api-trigger`](#post-req-to-notify-user-for-api-trigger)         | apipy              | Meant to notify users for an API trigger; answers success without sending anything                                     |
| POST   | [`/req-to-notify-user-for-qr-job`](#post-req-to-notify-user-for-qr-job)                   | apipy              | Notify users about a task created from a QR form                                                                       |
| POST   | [`/req-to-notify-user-on-new-userbusiness`](#post-req-to-notify-user-on-new-userbusiness) | apipy              | Notify a user who was added to a group or site                                                                         |
| POST   | `/req-to-notify-user-v1`                                                                  | apipy              | Send push notifications to users (v1) (no caller)                                                                      |
| POST   | `/user-devices`                                                                           | apipy              | List a user's devices (no caller). Always fails: it calls a method that doesn't exist                                  |
| GET    | [`/user-notification-settings`](#get-user-notification-settings)                          | apipy              | Get the caller's notification settings                                                                                 |
| POST   | [`/v3/scheduler/reminder-notification`](#post-v3schedulerreminder-notification)           | apipy              | Send planned-task reminder notifications for py\_scheduler                                                             |

Notes on the table:

* Rows marked "(no caller)" have no caller in any client or service clone. The php-apis actions appear at most in the apps' endpoint registries and constants, and in the survey code below, which never runs; the apipy routes appear nowhere. Whether to remove them is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* The survey routes have no caller because nothing opens the in-app surveys. The iOS survey check (`survey_check`) runs only from `checkForNPS`, whose only observer is commented out with the note "Commented as added survicate for replacement", and every post of its notification is commented out too; the survey screens that send `survey_feedback` open only from that check (ios @ aa31967ac8, `SnapFix/BusinessListingVC.swift:1458`, `:3070-3088`, `:3130-3146`, `SnapFix/HomeVC.swift:544`, `SnapFix/PMFS/PMFSBaseVC.swift:116-118`). Android's survey sheets also send `survey_feedback`, but no code creates them (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/bottomSheet/NPSBottomSheet.java:262`, `app/src/main/java/gmail/com/snapfixapp/bottomSheet/PMFSBottomSheet.java:285`). No code calls the NPS actions or `/v1/app/user/survey` either \[[ASK-10](https://github.com/snapfix/docs/blob/main/ASK.md#ask-10-which-differences-between-the-ios-and-android-apps-are-intended)].
* What the uncalled routes can do: the device-token reads return any user's or group's push tokens, and `POST /fbb_devicetoken` stores a token for any group. The group token table, `firebase_business_device_token`, is not in the staging schema, so the three group routes may fail there \[[ASK-169](https://github.com/snapfix/docs/blob/main/ASK.md#ask-169-does-production-have-the-group-device-token-table)]. The generic table actions create, change and delete any notification row by UUID. Both apps download the group and global notification rows into local tables, but no screen reads them \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]. `/user-devices` calls `_findUserDevices`, which apipy doesn't define, so it fails with HTTP `500` (apipy @ 0e83c85e5a, `app.py:4204-4220`).
* The php-apis dispatchers accept any method except `OPTIONS`. The table shows `POST` for `get_mkt_popup`, which both apps send, and `ANY` for actions no client sends.
* `/req-to-notify-group-admin` keeps its section, though no running client reaches its php-apis callers today; see its section.

## Related routes

Routes under the same paths or names that belong to other groups:

* **Chat pushes:** `POST /v1/app/notification/send` is in [Chat](https://docs.snapfix.com/engineering-reference/api/chat.md#post-v1appnotificationsend). The web, iOS and Android send their Firebase chat pushes (messages, mentions and reactions) through it, and it takes its receivers and text from the caller.
* **Task reminders:** `GET`, `POST` and `DELETE /job-reminder/{job_uuid}` and `POST /job-reminders` save a task's reminder settings; they are in [Tasks](https://docs.snapfix.com/engineering-reference/api/tasks.md#get-job-reminderjob_uuid), with `webcust_update_job_reminder` and `webcust_create_jobnotif`.
* **Task notifications:** the `save_pri_job_notif` action and its siblings (`*_pri_job_notif`) are in [Tasks](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_notif).
* **Server-only device tokens:** `read_server_only_device_user_token` and `save_server_only_device_user_token` are in [Users](https://docs.snapfix.com/engineering-reference/api/users.md).
* **Pre-registration survey:** `GET` and `POST /v1/guest/survey/prereg` are in [Onboarding](https://docs.snapfix.com/engineering-reference/api/onboarding.md).
* **Staff:** the marketing popup admin routes (`/v1/admin/marketing-popups` and the `admin_*_mkt_popup` actions) and the pre-registration survey admin routes (`/v1/admin/survey`) are in [Staff](https://docs.snapfix.com/engineering-reference/api/staff.md).
* **Features and screens:** [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md), [Reminders](https://docs.snapfix.com/product/features/notifications/reminders.md), [Marketing popups](https://docs.snapfix.com/product/features/notifications/marketing-popups.md), [Feedback surveys](https://docs.snapfix.com/product/features/notifications/feedback-surveys.md), and the [notification screens](https://docs.snapfix.com/how-the-apps-work/screens/notifications.md).

## Push delivery

Every apipy push route here ends in one sender, `_initNotificationV2` (apipy @ 0e83c85e5a, `model/feature_notification.py:2312-3545`). The synchronous routes reach it through `_initNotification`, which hands over at once (`:102-110`); the old FCM code after the hand-over never runs. `/req-to-notify-user` runs the sender in a background task. api\_php\_live\_v2 sends its own task and chat pushes to FCM without apipy (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/TokenService.php:106-147`).

```mermaid
flowchart LR
  web["web_app_v2"] -- "req-to-notify-user" --> sender["apipy sender"]
  apps["iOS and Android"] -- "req-to-notify-user" --> sender
  php["php-apis"] -- "sign-up, invitation and queue routes" --> sender
  auth["authpy"] -- "QR form and invitation routes" --> sender
  sched["py_scheduler"] -- "reminder routes" --> sender
  sender -- "FCM messages" --> devices["Devices"]
  sender -- "one row per call" --> logs["tPri_Log_NotifAPIRequests"]
```

How the sender chooses devices and the kind of push; the first rule that matches a device wins (`model/feature_notification.py`):

* **Devices:** the receivers' devices in [`firebase_user_device_token`](https://docs.snapfix.com/engineering-reference/db/tables/firebase_user_device_token.md), the newest row of each device (`:2378-2423`). A device whose newest row has no token gets nothing (`:2503`), which is how a sign-out stops pushes ([POST /fbu\_devicetoken](#post-fbu_devicetoken)).
* **The sender's devices:** the sender is `sender_user_uuid`, or else `notification_body.user`. The device named in `sender_firebase_device_id` gets nothing, and the sender's other devices get a silent push, except for type 51 (`:2357-2376`, `:2490-2491`, `:2531-2537`).
* **Silent:** a receiver who muted the group, a device with `notifications` 0, a message type of 100 or more, and the types in a fixed list (`:2538`).
* **Visible whatever the switches say:** types 80, 81, 90 and 98, on devices with `notifications` 1 (`:2545`).
* **Visible when the device's switch is on:** type 6 (`fJobCreated`), 44 (`fJobAssignedToMe`, for the users listed in `extra`), 1 (`fChatCreated`), 58 (`fJobReminderActivated`), 73 (`fTodoCompleted`); changes to priority tasks and type 33 by the three priority switches, and status changes (19 and 61) by the three status switches (`:2552-2785`). Every other type is silent (`:2787-2793`). That includes the sign-up notice to group admins (type 99) and, unless its task is a priority task, the planned-task reminder (type 51).
* **Switches:** the per-type switches come from each device row's `notifications_settings`, which [POST /fbu\_devicetoken](#post-fbu_devicetoken) keeps in step with the user's settings. A missing task, chat, reminder or checklist switch counts as on, a missing status or priority switch as off (`:2507-2529`). A device whose settings have no `fTodoCompleted` (older app versions) follows an older rule set with `JobCreate`, `ColourUpdate`, `FlagUpdate`, `OtherUpdate`, `TaskCreatedByMe` and `TaskAssignedToMe` (`:2801-2921`).
* **Mute:** a receiver counts as muted when its `receivers` item has `group_mute` 1. When the request lists `notification_receiver_uuids` and `notification_body` names a group (`businessUUID`), the sender reads the Redis key `nm_<user>_<group>` instead (`:2325-2342`). Only apipy's `update-cache.py` writes those keys, from the `notifMute` column of [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) (apipy @ 0e83c85e5a, `update-cache.py:11-45`); the repos don't show how often it runs \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. A `notification_receiver_uuids` request that names no group mutes nobody.
* **Sending:** visible and silent pushes go out in separate multicast batches per platform, through the Firebase Admin SDK (`messaging.send_each_for_multicast`, `:2957-3489`). Silent pushes carry `silent: true` in their data.
* **Log:** one [`tPri_Log_NotifAPIRequests`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_notifapirequests.md) row per call, with the whole request, the token counts and the FCM answers (`:3507-3542`).
* **Errors:** any failure in the sender becomes an error with the exception's text (`:3544-3545`). The synchronous routes answer it as `result` `false` with that text; `/req-to-notify-user` only logs it.

## PUT /v1/app/notification/{businessUuid}/mute

Mutes a group's notifications for the caller: sets `notifMute` to 1 on the caller's own membership of the group. The web sends it after the user confirms "Mute".

* **Auth:** user token. Any member may mute a group for themselves. The route finds the caller's newest live membership of the group and changes only that row (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/UserAssetBusinessService.php:182-194`, `app/Http/Controllers/v1/Versions/v1_0/App/UserAssetBusinessController.php:200-211`).
* **Used by:** web (`GroupHttpService.changeGroupNotificationState` with `state` true, from the bell in the group list's grid and table views: web\_app\_v2 @ 0989b8e685, `src/app/services/group/group-http/group-http.service.ts:117-126`, `src/app/pages/fix/group-list/group-list-grid-view/group-list-grid-view.component.ts:97-101`, `:140-145`, `src/app/pages/fix/group-list/group-list-table-view/group-list-table-view.component.ts:96-100`, `:139-144`). The apps don't call it: they keep `notifMute` in their synced copy of [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) (ios @ aa31967ac8, `Models/UserBusiness.swift:88`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/model/UserBusiness.java:220-222`).

**Request**

| Name           | In   | Type   | Required | Rules                                                   |
| -------------- | ---- | ------ | -------- | ------------------------------------------------------- |
| `businessUuid` | path | string | yes      | The group. The caller must have a live membership of it |

No body.

**Response** `200`

```json
{
  "status": "success",
  "message": "Notification successfully disabled",
  "data": null
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` "Resource not found" when the caller has no live membership of the group, also after being removed from it (`firstOrFail`, which `app/Exceptions/Handler.php:46-47` turns into `404`).

**Side effects:**

* Sets `notifMute` to 1 on the caller's [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row. The model's update hook also sets `fServerTs` and `uuid_tUser_ModifiedBy` (`app/Traits/ModelUpdate.php:25-28`).
* Sends no push and writes no other table.
* Who reads the flag: api\_php\_live\_v2's own task and chat pushes send a muted member a silent push instead (`app/Services/TokenService.php:106-147`, `:255-267`). apipy reads the mute from the request or from its cache ([Push delivery](#push-delivery)) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. The chat push route doesn't read it ([Chat](https://docs.snapfix.com/engineering-reference/api/chat.md#post-v1appnotificationsend)).

## PUT /v1/app/notification/{businessUuid}/unmute

Unmutes a group's notifications for the caller: sets `notifMute` to 0 on the caller's own membership. The web sends it at once, with no dialog.

* **Auth:** user token, as for [mute](#put-v1appnotificationbusinessuuidmute) (`app/Http/Controllers/v1/Versions/v1_0/App/UserAssetBusinessController.php:219-230`).
* **Used by:** web, the same `changeGroupNotificationState` call with `state` false, when the group is muted (web\_app\_v2 @ 0989b8e685, `src/app/services/group/group-http/group-http.service.ts:117-126`, `src/app/pages/fix/group-list/group-list-grid-view/group-list-grid-view.component.ts:97-101`, `src/app/pages/fix/group-list/group-list-table-view/group-list-table-view.component.ts:96-100`). The apps don't call it.

**Request**

| Name           | In   | Type   | Required | Rules                                                   |
| -------------- | ---- | ------ | -------- | ------------------------------------------------------- |
| `businessUuid` | path | string | yes      | The group. The caller must have a live membership of it |

No body.

**Response** `200`

```json
{
  "status": "success",
  "message": "Notification successfully enabled",
  "data": null
}
```

**Errors:** as for [mute](#put-v1appnotificationbusinessuuidmute).

**Side effects:** sets `notifMute` to 0 on the caller's [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row, with the same timestamp changes as mute. Sends no push.

## GET /v1/app/parents/{uuid}/popups

Returns the marketing popups that are active now for a site: those switched on, aimed at the site or at every site, whose campaign window contains the current time. The web's Fix page checks it.

* **Auth:** user token. The route checks that the site exists, not that the caller belongs to it, so any signed-in user gets any site's popups (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/ParentController.php:407-432`).
* **Used by:** web (`MarketingPopupService.getMarketingPopup`, from `checkMarketingPopup`, which the Fix page runs after it loads and when the site changes: web\_app\_v2 @ 0989b8e685, `src/app/services/marketing-popup/marketing-popup.service.ts:35-41`, `:114-121`, `src/app/pages/fix/fix.component.ts:77`, `:278`, `:302`). The web checks at most once every `MARKETING_POPUP_CHECK_INTERVAL` hours (5), with one timer for all sites (`marketing-popup.service.ts:103-112`, `src/app/shared/config.ts:117`). The apps use [`get_mkt_popup`](#post-actionget_mkt_popup) instead.

**Request**

| Name   | In   | Type   | Required | Rules    |
| ------ | ---- | ------ | -------- | -------- |
| `uuid` | path | string | yes      | The site |

No query and no body.

**Response** `200`: `data` is a list of [marketing popup objects](#marketing-popup-object), empty when no popup is active.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "700",
      "name": "Spring offer",
      "iosDisable": 0,
      "androidDisable": 0,
      "webDisable": 0,
      "imagePortraitUrl": "https://example.com/portrait.png",
      "imageLandscapeUrl": "https://example.com/landscape.png",
      "campaignUrl": "https://example.com/offer",
      "localeBcp47": "en-GB",
      "monStartAfterMidnightMs": 32400000,
      "monDurationMs": 3600000,
      "tueStartAfterMidnightMs": 32400000,
      "tueDurationMs": 3600000,
      "wedStartAfterMidnightMs": null,
      "wedDurationMs": null,
      "thuStartAfterMidnightMs": null,
      "thuDurationMs": null,
      "friStartAfterMidnightMs": null,
      "friDurationMs": null,
      "satStartAfterMidnightMs": null,
      "satDurationMs": null,
      "sunStartAfterMidnightMs": null,
      "sunDurationMs": null
    }
  ]
}
```

* The route keeps the live popups with `fActive` 1 whose targeting list (`parent_uuid_json`) is empty, holds `null` or contains the site's ID, and whose `campaignStartTs` to `campaignEndTs` contains the current time (`app/Services/ParentService.php:425-433`, `ParentController.php:414-427`).
* It doesn't check the weekday windows; the clients do. The targeting list, the campaign dates and the time zone are not returned.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` "Resource not found" for an unknown or deleted site (`app/Services/ParentService.php:278-304`).

**Side effects:** none.

## POST ?action=get\_mkt\_popup

The apps' version of [GET /v1/app/parents/{uuid}/popups](#get-v1appparentsuuidpopups): the same popups, under the table's column names.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]): the action is not on the dispatcher's open list (php-apis @ 238ca4414e, `html/api/snapfix/index.php:355`, `:383-385`). It reads only `parent_uuid` and checks no membership, so the token doesn't say who is asking and any signed-in user gets any site's popups (`htmlphp/api/snapfix/class/class.functions.php:44291-44301`).
* **Used by:** iOS (`MarketingPopupManager.callAPI`, from `BusinessListingVC.viewDidLoad`: ios @ aa31967ac8, `SnapFix/MarketingPopupManager.swift:25-29`, `SnapFix/BusinessListingVC.swift:156`) and Android (`GroupListingFragment.checkForMarketingData`, when the group list is shown and from the tooltip code: android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/GroupListingFragment.java:317-318`, `:1189-1200`, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:4619`, `:4635`, `app/src/main/java/gmail/com/snapfixapp/network/ApiService.java:434-436`). Both send a JSON body.

**Request** (JSON body)

| Name          | In   | Type   | Required | Rules                                                                                     |
| ------------- | ---- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `parent_uuid` | body | string | yes      | The site. Missing or blank: "invalid params"; no live site with that ID: "invalid parent" |

**Response** `200`: `data` is a list of [marketing popup objects](#marketing-popup-object) under the table's column names; the dispatcher adds `serverTs`.

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "uuid": "700",
      "name": "Spring offer",
      "ios_disable": 0,
      "android_disable": 0,
      "web_disable": 0,
      "image_portrait_url": "https://example.com/portrait.png",
      "image_landscape_url": "https://example.com/landscape.png",
      "campaign_url": "https://example.com/offer",
      "locale_bcp47": "en-GB",
      "mon_startAfterMidnightMs": 32400000,
      "mon_durationMs": 3600000,
      "sun_startAfterMidnightMs": null,
      "sun_durationMs": null
    }
  ],
  "serverTs": 1794387595000
}
```

The example shows Monday and Sunday; the other weekdays have the same two fields. The action keeps the same popups as the Laravel route: live, `fActive` 1, aimed at the site or at every site, with a campaign window that contains the current time. It removes `campaignStartTs` and `campaignEndTs` from each row and sends the weekday windows as they are (`class.functions.php:44303-44363`).

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (empty body: `html/api/snapfix/index.php:1026-1032`, `htmlphp/api/snapfix/config/lang/en.php:6`); "invalid params"; "invalid parent". Token errors as in [User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens).

**Side effects:** none.

## POST /fbu\_devicetoken

Saves a device of the signed-in user for pushes: its device ID, push token, app version and notification settings, and with them the user's notification settings. The apps send it when they get a push token and when the notification switches change. At sign-out they send it without a token, which stops pushes to that device.

* **Auth:** user token (`@jwt_required()`). The form's `uuid_tUser` must be the token's user, so a caller can save only their own devices (apipy @ 0e83c85e5a, `app.py:1460-1477`). The abuse check runs first ([Blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).
* **Used by:** iOS (`FCMHelper.sendDeviceTokenToFirebase` after sign-in, after the settings read and from the notification settings screen; `removeDeviceToken`, with no token, at sign-out through `deleteDeviceTokenFB`: ios @ aa31967ac8, `SVProgressHUD/FCMHelper.swift:1704-1732`, `:1733-1756`, `:1969-1970`, `SnapFix/RegisterHelper.swift:58`, `SnapFix/BusinessListingVC.swift:297-300`, `SnapFix/New Profile/Notification Settings/View Model/NotificationSettingsViewModel.swift:85`, `AppUtility.swift:4494`). Android (`FirebaseTokenUtils.saveDeviceToken` when the app gets its push token and when the profile screen sends its switches; `deleteDeviceToken`, with no token, at sign-out: android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/FirebaseTokenUtils.java:40-105`, `app/src/main/java/gmail/com/snapfixapp/activity/BaseFirebaseActivity.java:151`, `app/src/main/java/gmail/com/snapfixapp/service/MyFirebaseMessagingService.java:183`, `app/src/main/java/gmail/com/snapfixapp/activity/MyProfileActivity.kt:1722-1725`, `app/src/main/java/gmail/com/snapfixapp/utils/LoginDialogUtils.java:127`, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:4310`). The web has the endpoint in its list but never calls it.

**Request** (form fields)

| Name                     | In     | Type                 | Required | Rules                                                                                                                                                                               |
| ------------------------ | ------ | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tUser`             | body   | string               | yes      | The caller's user ID. Missing, empty or another user's: "invalid uuid\_tUser"                                                                                                       |
| `device_id`              | body   | string               | yes      | The device's ID. A Swift `Optional("…")` wrapper is removed. Missing or empty: "invalid device\_id"                                                                                 |
| `device_token`           | body   | string               | no       | The push token. Missing or empty is stored as an empty string, and such a device gets no push                                                                                       |
| `device_type`            | body   | string               | yes      | `ios`, `android` or `web`. Missing or empty: "invalid device\_type"                                                                                                                 |
| `notifications`          | body   | string               | yes      | The all-notifications switch, `1` or `0`. Missing or empty: "invalid notifications field"                                                                                           |
| `notifications_settings` | body   | string (JSON object) | yes      | The per-type switches as JSON text, such as `fJobCreated` and `fChatCreated`. Missing or empty: "invalid notifications\_settings"; text that is not JSON gives the parser's message |
| `Device-App-Version`     | header | string               | no       | The app version, such as `6.10.35`. Stored with the device row, and decides whether the settings are copied (below)                                                                 |

**Response** `200`: `data` is the device row as stored, with `notifications_settings` as an object (`model/t_firebase_user_device_token.py:72-85`, `:679`). A `web` device gets no device row, and `data` is then the user's [`tPri_UserNotifSettings`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_usernotifsettings.md) row (`:681`).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "id": 42,
    "uuid": "9f1c2b7e-3d4a-4c5b-8e6f-1a2b3c4d5e6f",
    "uuid_tUser": "200",
    "device_id": "7C0F2A1B-5D3E-4F60-9A8B-112233445566",
    "device_token": "example-push-token",
    "device_type": "android",
    "device_last_seen_ts": null,
    "notifications": 1,
    "notifications_settings": { "fAllNotifications": 1, "fJobCreated": 1, "fChatCreated": 1 },
    "device_sf_version": "6.10.35",
    "device_sf_version_int": 600100035,
    "fCreatedTs": 1794387595000,
    "fServerTs": 1794387595000,
    "uuid_tUser_CreatedBy": "admin"
  }
}
```

**Errors:** `200` with `result` `false`: "invalid uuid\_tUser", "invalid device\_id", "invalid device\_type", "invalid notifications field", "invalid notifications\_settings" (`app.py:1476-1497`); the JSON parser's message when `notifications_settings` is not JSON; "please provide all the notification settings." when the settings row can't be updated (`model/t_firebase_user_device_token.py:612-616`). Token errors as in [User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens).

**Side effects** (`model/t_firebase_user_device_token.py:414-690`):

* Inserts a [`firebase_user_device_token`](https://docs.snapfix.com/engineering-reference/db/tables/firebase_user_device_token.md) row for an `ios` or `android` device on every call, also when nothing changed, with `uuid_tUser_CreatedBy` "admin" (`:430-471`). The sender uses each device's newest row.
* Only when `device_token` is not empty and the app version is above 6.10.28, or the type is `web` (`:475-476`):
  * copies `notifications` and `notifications_settings` onto the newest row of every device of the user (`:478-520`);
  * writes the switches sent to the user's [`tPri_UserNotifSettings`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_usernotifsettings.md) row, or inserts the row with the switches sent and defaults for the rest: every switch on except `fChatCreated` and `fOtherNotifications` (`:522-676`).
* A sign-out call adds a row with an empty token. That row becomes the device's newest, so the [sender](#push-delivery) skips the device from then on.
* Sends no push.

## POST /job/due-reminder-notification

Sends a task's due-date reminder: a push to its live assignees, and a line in the task's chat. py\_scheduler calls it for each due-date schedule that falls due.

* **Auth:** none. `@jwt_required()` and the abuse check are commented out, so anyone who can reach the host can run the reminder for any task UUID (apipy @ 0e83c85e5a, `app.py:3672-3680`).
* **Used by:** py\_scheduler (`cronScheduleV3._initSchedule` finds the `duedatenotif` schedules and posts each task's `job_uuid`: py\_scheduler @ c8b1344036, `models/cron_schedule_v3.py:263-270`, `:341-347`, run by `schedulev3.py:9-11`). It sends a Basic login written in its code (`:297-306`), which the route doesn't check.

**Request** (JSON body)

| Name       | In   | Type   | Required | Rules                                                        |
| ---------- | ---- | ------ | -------- | ------------------------------------------------------------ |
| `job_uuid` | body | string | yes      | The task. Missing or not a string: `"job_uuid" is mandatory` |

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false`: `"job_uuid" is mandatory`; "invalid job" when the task is deleted, archived, green or has no due date, or its group or site is deleted; "invalid job assignees" when no live user is assigned (`model/feature_notification.py:1884-1937`); the error text of any other failure (`:2062-2063`).

**Side effects:**

* Sends type 80 to the live assignees through the [sender](#push-delivery): title "Due Reminder for {task}", text "{task} in {group} is due on {date}", or "Overdue : {task}" once the due time has passed. `{date}` is the due time in the site's time zone, as "Nov 14 2026 at 09:00" (`:1939-1968`). Type 80 is visible on every device with notifications on, whatever its switches say, except for receivers who muted the group.
* Adds a [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) line of type 80, "This task is due on {date}" or "Overdue: This task was due on {date}", and sets `fJobChatModifiedTs`, `fModifiedTs` and `fServerTs` on [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (`:1970-2060`). The line is posted in the name of the task's due-date user, else its creator, when that user is a live member of the group, else of a group admin; with none of them, no line is written.
* Doesn't change [`tPri_JobReminder`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobreminder.md): the calls to `updateJobReminderTable` are commented out (`:1936`, `:2060`).
* There is no interval check: each call sends again.

## POST /job/reminder-notification-v2

Sends a task's reminder: a push to its live assignees, and a "Task reminder" line in the task's chat. py\_scheduler calls it for each task reminder that falls due. A one-time reminder then switches the task's reminder off.

* **Auth:** none. `@jwt_required()` and the abuse check are commented out (apipy @ 0e83c85e5a, `app.py:3643-3651`).
* **Used by:** py\_scheduler (the `tasknotif` schedules: py\_scheduler @ c8b1344036, `models/cron_schedule_v3.py:104-116`, `:172-179`). It sends the same Basic login from its code (`:129-138`).

**Request** (JSON body)

| Name       | In   | Type   | Required | Rules                                                        |
| ---------- | ---- | ------ | -------- | ------------------------------------------------------------ |
| `job_uuid` | body | string | yes      | The task. Missing or not a string: `"job_uuid" is mandatory` |

**Response** `200`: `result` `true`, `message` "success" and `serverTs`, as for [the due-date route](#post-jobdue-reminder-notification).

**Errors:** `200` with `result` `false`: `"job_uuid" is mandatory`; "invalid job" when the task is deleted, its reminder is off (`fEnableTaskReminder` 0), or its group or site is deleted (`model/feature_notification.py:1709-1735`); "invalid job assignees" when no live user is assigned, after the route has moved the task's [`tPri_JobReminder`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobreminder.md) row on to 09:05 the next day, site time (`:1756-1759`, `:2065-2089`); the error text of any other failure (`:1881-1882`).

**Side effects:**

* Sends type 58 to the live assignees through the [sender](#push-delivery): title the task's title, text "You have a reminder to get things done in {group}" (`:1765-1779`). It is visible on devices whose reminder switch (`fJobReminderActivated`) is on.
* Sets `fEnableTaskReminder` on [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) to 0 when the task's `tasknotif` schedule is a single run, else to 1 (`:1781-1810`).
* Adds a "Task reminder" [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) line of type 58 and sets the task's chat and modified times (`:1812-1878`). The line is posted in the name of the user who set the reminder, else the creator, when that user is a live member of the group, else of a group admin.
* There is no interval check. The 20-hour limit exists only in the first version, `/job/reminder-notification`, and the debug route skips it (`:1601-1603`).

## POST /req-to-notify-group-admin

Sends a push at once to the receivers named in the body, through the [sender](#push-delivery). php-apis's sign-up code uses it to tell a group's admins that a new user has registered and joined the group (type 99).

* **Auth:** none. `@jwt_required()` is commented out (apipy @ 0e83c85e5a, `app.py:2031-2033`). The abuse check runs ([Blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).
* **Used by:** php-apis. `registerNewUser650`, `registerNewUserV8` and `registerNewUserV9` look up, in [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md), the admins of each group the new user joined through a group invitation, and send one push per group (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:11326-11359`, `:23815-23847`, `:26097-26130`). They run from the sign-up actions `register_new_user_v650`, `register_new_user_v7`, `register_new_user_v8`, `register_new_user_v9` and `webcust_register_new_user` (`html/api/snapfix/index.php:2802-2804`, `:2598-2600`, `:1850-1852`, `:1648-1650`; `html/api/snapfix/web/index.php:1930-1932`). No running client reaches those actions today: authpy's sign-up proxies return before they call php-apis (authpy @ 5d5758661c, `app.py:555-565`, `:1281-1291`, `:1298-1313`), and the iOS screens that call `register_new_user_v650` sit in a pager that nothing opens (ios @ aa31967ac8, `SnapFix/PageViewControllerRegister.swift:34-35`) \[[ASK-10](https://github.com/snapfix/docs/blob/main/ASK.md#ask-10-which-differences-between-the-ios-and-android-apps-are-intended)].

**Request** (JSON body). The other no-login push routes take the same body.

| Name                          | In   | Type             | Required | Rules                                                                                                                                                                                                                              |
| ----------------------------- | ---- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `notification_body`           | body | object           | yes      | The push's data, sent on to the devices. It needs a numeric `type`; without one the route fails with a server error (`model/feature_notification.py:102-105`). Missing or not an object: `Object "notification_body" is mandatory` |
| `notification_receiver_uuids` | body | array of strings | yes      | The receivers' user IDs. Missing or not an array: `List "notification_receiver_uuids" is mandatory`; empty: `invalid notification_receiver_uuids`                                                                                  |
| `notification_msg_data`       | body | object           | no       | The visible text: `title`, `body` and `sound`. The sender drops `sound`                                                                                                                                                            |
| `sender_user_uuid`            | body | string           | no       | The user who caused the push; their other devices get a silent push. Not checked                                                                                                                                                   |
| `sender_firebase_device_id`   | body | string           | no       | A device that gets no push                                                                                                                                                                                                         |

The sign-up code sends `type` 99, `ts`, `text` ("{name} has registered for Snapfix and has been added to {group}") and `businessUUID`, an empty title, and the new user as `sender_user_uuid`.

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000
}
```

`result` `true` means the pushes were handed to FCM inside the request; whether a device got one is only in the log row.

**Errors:** `200` with `result` `false`: `Object "notification_body" is mandatory`; `List "notification_receiver_uuids" is mandatory`; `invalid notification_receiver_uuids`; the error text of a failed send (`app.py:2068-2071`). A blocked caller gets the abuse check's answer.

**Side effects:** the pushes and one log row, through the [sender](#push-delivery). Type 99 has no visible rule, so the admins get a silent push. Nothing else changes.

## POST /req-to-notify-site-admin

Sends a push at once to the receivers named in the body: the admins of a site an invited user has just joined (type 98).

* **Auth:** none. `@jwt_required()` is commented out (apipy @ 0e83c85e5a, `app.py:2080-2082`). The abuse check runs.
* **Used by:** authpy (`_sendInvitationAcceptanceAcknowledgement`, when a signed-in user opens an invitation link, `GET /dl-ctx/{dynamicLinkUUID}`: authpy @ 5d5758661c, `model/feature_user_auth.py:1214-1358`, called from `model/feature_token_ops.py:3611` and `:3681`, `app.py:2404-2454`). It emails or texts each site admin first, then pushes, and it stops when the link, its sites, the user or a site admin can't be found (`model/feature_user_auth.py:1215-1250`). php-apis (`sendInvitationAcceptanceAcknowledgement`, which reads the site admins from [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md), from `setUserPasswordV9` behind the `set_user_password_v9` action: php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:47772-47929`, `htmlphp/api/snapfix/class/cognito.functions.php:1207`, `html/api/snapfix/index.php:955-957`).

**Request, response and errors:** as for [`/req-to-notify-group-admin`](#post-req-to-notify-group-admin). Both callers send `type` 98, `ts`, `text` and `siteUUID`, an empty title, one site admin per call, and the new user as `sender_user_uuid`.

**Side effects:** the pushes and one log row, through the [sender](#push-delivery). Type 98 is visible on every device with notifications on. Nothing else changes; the emails and texts are authpy's and php-apis's own.

## POST /req-to-notify-user

Queues a push to the users named in the request and answers at once; a background task runs the [sender](#push-delivery). The apps send their task and group pushes through it, and the web its task reminder pushes.

* **Auth:** user token (`@jwt_required()`). Any valid token is enough: the route doesn't check that the caller shares a group, task or chat with the receivers, and it takes the text from the request (apipy @ 0e83c85e5a, `app.py:1833-1835`). It skips the abuse check (`:1840-1843`).
* **Used by:** web (`CommonService.requestToNotifyUsers`, from the task reminder dialog and the task reminder component: web\_app\_v2 @ 0989b8e685, `src/app/services/common/common.service.ts:107-142`, `src/app/pages/task/task-quick-actions/task-reminder-dialog/task-reminder-dialog.component.ts:244`, `src/app/pages/task/task-reminder/task-reminder.component.ts:257`). iOS (`APIManager.sendMessageTokenServer`, from `FCMHelper.sendMessageToGroup`, which the task and group code calls, for example at `AppUtility.swift:331`, `:387`, `:423`, `:430` and `Managers/TaskManager.swift:4509`: ios @ aa31967ac8, `APIManagers/APIManager.swift:634-640`, `SVProgressHUD/FCMHelper.swift:40`, `:150-157`). Android (`FirebaseSenderUtils.sendNotificationRequest`, from `callSendNotificationAPI` for task and task chat events: android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/FirebaseSenderUtils.java:325`, `:563-592`, `app/src/main/java/gmail/com/snapfixapp/network/ApiService.java:328-330`). iOS and Android send multipart forms with both sender fields; the web sends `receivers` and an `is_silent` field, which the route ignores.

**Request** (form fields; the JSON values are sent as text)

| Name                          | In   | Type                 | Required       | Rules                                                                                                                                                                                                   |
| ----------------------------- | ---- | -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `notification_body`           | body | string (JSON object) | yes            | The push's data, sent on to the devices. The sender reads `type` (a number), `user`, `businessUUID`, `job` and `extra`. Missing or not an object: `Object "notification_body" is mandatory`             |
| `notification_receiver_uuids` | body | string (JSON array)  | one of the two | The receivers' user IDs. Not an array: `List "notification_receiver_uuids" is mandatory and must be a valid JSON array.`                                                                                |
| `receivers`                   | body | string (JSON array)  | one of the two | One object per receiver: `user_uuid`, and `group_mute`, 1 when the receiver muted the group, which makes the push silent. Not an array: `List "receivers" is mandatory and must be a valid JSON array.` |
| `notification_msg_data`       | body | string (JSON object) | no             | The visible text: `title`, `body` and `sound`. The sender drops `sound`                                                                                                                                 |
| `sender_user_uuid`            | body | string               | no             | The user who caused the push; their other devices get a silent push. Not checked against the caller                                                                                                     |
| `sender_firebase_device_id`   | body | string               | no             | The sender's device, which gets no push                                                                                                                                                                 |

Send exactly one of the two receiver lists. Both give `Only one of "notification_receiver_uuids" or "receivers" should be present, not both.`; neither gives `Either "notification_receiver_uuids" or "receivers" is mandatory.`

**Response** `200`, before any push goes out:

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` for the checks above (`app.py:1860-1893`), and the JSON parser's message for a value that isn't JSON. Token errors as in [User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens). Failures in the background task, such as an empty receiver list or a body without `type`, are only logged; the caller has already had its success (`app.py:1910-1922`, `model/feature_notification.py:2354-2355`).

**Side effects:** a Celery task runs the [sender](#push-delivery) (`app.py:1896`, `:1910-1918`): the pushes and one log row. Nothing else changes.

## POST /req-to-notify-user-for-api-trigger

Meant to send the "API update required" push that php-apis asks for after it saves queued changes, so that the members' apps read the queue again. It answers success and sends nothing.

* **Auth:** none. The route returns on its first line, before any check (apipy @ 0e83c85e5a, `app.py:2171-2175`).
* **Used by:** php-apis: `saveQueueLog`, behind the `save_queue` action, and the four `triggerAPIUpdateNotification` helpers, which group, user and task code calls from 19 places (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:38966`, `:39070`, `:39208`, `:39239`, `:39282`, `:39360`, `html/api/snapfix/index.php:1133-1136`). The helpers run only while `LEGACY_QUEUE_SUPPORT` or `WEB_QUEUE_SUPPORT` is on (`class.functions.php:39183`, `:39227`, `:39258`, `:39301`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. php-apis sends the body of the other push routes, with `type` -1 and the text "API update required".

**Request:** any body; the route reads none of it.

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000
}
```

**Errors:** none; the route never answers `result` `false`.

**Side effects:** none. The members' apps get no "API update required" push from it.

## POST /req-to-notify-user-for-qr-job

Sends a push at once about a task created from a QR form (type 6) to the receivers named in the body.

* **Auth:** none. `@jwt_required()` is commented out (apipy @ 0e83c85e5a, `app.py:2214-2216`). The abuse check runs. Its only caller is authpy's QR form save, which checks the shared Basic login first (authpy @ 5d5758661c, `app.py:1434-1436`).
* **Used by:** authpy (`_createJobFromQR`, run by `POST /qr-form/{uuid}`: authpy @ 5d5758661c, `model/feature_qrform.py:143`, `:969-1024`, `app.py:1414-1444`), which the public QR form sends (qr\_forms @ bdfc4f20a5, `src/app/services/form/form.service.ts:34-39`).

**Request, response and errors:** as for [`/req-to-notify-group-admin`](#post-req-to-notify-group-admin). authpy sends:

* `notification_body`: `type` "6", the task's creator as `user` and `name`, `userBusiness`, `job`, `ts`, `isdeleted`, `extra` (the form's image), `businessUUID`, and the text `<b>{name}</b> Created Task` (`model/feature_qrform.py:974-981`).
* `notification_receiver_uuids`: the group's admins and the members who may view all tasks, then the task's assignees and followers (`:983-1016`). With nobody to notify, authpy doesn't call the route.
* `notification_msg_data`: the group's name as the title, the text as the body.
* `sender_user_uuid`: "admin", which matches no device (`:1020`).

**Side effects:** the pushes and one log row, through the [sender](#push-delivery). Type 6 is visible on devices whose new-task switch (`fJobCreated`) is on.

## POST /req-to-notify-user-on-new-userbusiness

Sends a push at once to a user who was just added to a group, or added to a site as an existing user, saying who added them (type 98). The php-apis function that calls it is named for group admins, but the receiver is the new member.

* **Auth:** none. `@jwt_required()` is commented out (apipy @ 0e83c85e5a, `app.py:2129-2131`). The abuse check runs.
* **Used by:** php-apis. `sendGroupAdminNotificationOnNewJoinee` runs when a membership is saved, from `checkAndSaveIntoUserBusinessTable`, `checkAndSaveIntoUserBusinessTableV2` and the web action `webcust_add_userbusiness` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:24097-24124`, `:4748`, `:38808`, `htmlphp/api/snapfix/class/webapp.functions.php:7186`, `html/api/snapfix/web/index.php:1539-1541`). `sendInvitationV2ForExistingUser` runs when an existing user is added to a site, from `addUsersV2ProxyPatchCall` (`class.functions.php:45028-45170`, `webapp.functions.php:7744`).

**Request, response and errors:** as for [`/req-to-notify-group-admin`](#post-req-to-notify-group-admin). php-apis sends `type` 98 and either "{inviter} has added you to the following Snapfix '{group}'" with the group's `businessUUID`, or "You have been added to {site}. Tap to view" with the site's `siteUUID`; the new member as the only receiver; an empty title; and the person who added them as `sender_user_uuid`.

**Side effects:** the push and one log row, through the [sender](#push-delivery). Type 98 is visible on every device with notifications on, unless the receiver muted that group.

## GET /user-notification-settings

Returns the caller's notification switches. The apps read it during their data download and on the notification settings screen; iOS reads it again once each time the app comes to the foreground.

* **Auth:** user token (`@jwt_required()`). The route reads the token's user and returns that user's row only; no parameter names a user (apipy @ 0e83c85e5a, `app.py:4457-4470`). The abuse check runs first.
* **Used by:** iOS (`ReadDataManager.getSettings`, from `Appdelegate/AppDelegate.swift:731-734` and `SnapFix/BusinessListingVC.swift:297-300`, and `NotificationSettingsViewModel.refreshFromServer` on the settings screen: ios @ aa31967ac8, `Managers/ReadDataManager.swift:484-500`, `SnapFix/New Profile/Notification Settings/View Model/NotificationSettingsViewModel.swift:32-33`). Android (the data download, the profile screen, and the token save when no settings are stored yet: android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/network/ReadDataManager.java:192`, `:796-800`, `app/src/main/java/gmail/com/snapfixapp/network/ReadDataManagerKotlin.kt:239`, `:999-1010`, `app/src/main/java/gmail/com/snapfixapp/activity/DownloadDataActivity.java:764-767`, `app/src/main/java/gmail/com/snapfixapp/activity/MyProfileActivity.kt:2261-2263`, `app/src/main/java/gmail/com/snapfixapp/utils/FirebaseTokenUtils.java:45`, `:135-139`). The web has the endpoint in its list but never calls it.

**Request:** none.

**Response** `200`: `data` is a [notification settings object](#notification-settings-object).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "fAllNotifications": 1,
    "fFirebaseChatCreated": 1,
    "fJobCreated": 1,
    "fJobAssignedToMe": 1,
    "fJobReminderActivated": 1,
    "fTodoCompleted": 1,
    "fChatCreated": 0,
    "fStatusJobCreatedByMe": 1,
    "fStatusJobAssignedtoMe": 1,
    "fStatusAllOtherJob": 1,
    "fPriorityJobCreatedByMe": 1,
    "fPriorityJobAssignedtoMe": 1,
    "fPriorityJobAllOther": 1,
    "fOtherNotifications": 0
  }
}
```

**Errors:** `200` with `result` `false`: "record(s) not found" when the caller has no live row in [`tPri_UserNotifSettings`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_usernotifsettings.md) (`app.py:4470-4476`, `config/constant.py:157`); "Error fetching notification settings: …" when the read fails (`model/feature_notification.py:2298-2300`). Token errors as in [User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens).

**Side effects:** none.

## POST /v3/scheduler/reminder-notification

Sends the reminder push of a planned task: "{task} is scheduled for tomorrow", which py\_scheduler builds each time a planner's reminder falls due, to the task's assignees who are still in the group.

* **Auth:** none. `@jwt_required()` is commented out (apipy @ 0e83c85e5a, `app.py:1981-1983`). The abuse check runs.
* **Used by:** py\_scheduler (`cronScheduleV3._initSchedule` finds the planner schedules with a reminder, keeps the assignees who are still live members of the group, and posts the push: py\_scheduler @ c8b1344036, `models/cron_schedule_v3.py:480-490`, `:560-661`). This call sends only a `Content-Type` header (`:658-661`).

**Request, response and errors:** as for [`/req-to-notify-group-admin`](#post-req-to-notify-group-admin). py\_scheduler sends `type` "51", the schedule's creator as `user`, `job` (the planned task, or "invalid-job-uuid" when the schedule has none), `businessUUID` and the text, the group's name as the title, and no `sender_user_uuid` (`models/cron_schedule_v3.py:561-566`).

**Side effects:** the pushes and one log row, through the [sender](#push-delivery). Type 51 has no visible rule, so the push goes out silent unless its task is a priority task.

## Marketing popup object

A campaign from [`mkt_popup`](https://docs.snapfix.com/engineering-reference/db/tables/mkt_popup.md), as [GET /v1/app/parents/{uuid}/popups](#get-v1appparentsuuidpopups) and [`get_mkt_popup`](#post-actionget_mkt_popup) return it. The Laravel route uses camelCase names (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/MarketingPopupResource.php:14-43`); the php-apis action uses the table's column names (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:44303-44363`).

| Laravel route                                                                    | php-apis action                                                                    | Type            | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `name`                                                                   | `uuid`, `name`                                                                     | string          | The campaign's ID and internal name                                                                                                                                                                                                                                                                                                                                                                                                             |
| `iosDisable`, `androidDisable`, `webDisable`                                     | `ios_disable`, `android_disable`, `web_disable`                                    | integer         | `1` hides the popup on that platform. The web skips a popup with `webDisable` set, iOS one with `ios_disable` set, and Android shows one only when `android_disable` is not 1 (web\_app\_v2 @ 0989b8e685, `src/app/services/marketing-popup/marketing-popup.service.ts:52`; ios @ aa31967ac8, `SnapFix/MarketingPopupManager.swift:80`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/GroupListingFragment.java:1252`) |
| `imagePortraitUrl`, `imageLandscapeUrl`                                          | `image_portrait_url`, `image_landscape_url`                                        | string or null  | The portrait and landscape images. The web picks the portrait one below a window width of 600 pixels (`marketing-popup.service.ts:54`)                                                                                                                                                                                                                                                                                                          |
| `campaignUrl`                                                                    | `campaign_url`                                                                     | string or null  | The link the popup opens (`marketing-popup.service.ts:81`)                                                                                                                                                                                                                                                                                                                                                                                      |
| `localeBcp47`                                                                    | `locale_bcp47`                                                                     | string or null  | The language the popup is for. The web shows it only when the browser's languages include it (`marketing-popup.service.ts:69`)                                                                                                                                                                                                                                                                                                                  |
| `monStartAfterMidnightMs`, `monDurationMs`, and the same pair for `tue` to `sun` | `mon_startAfterMidnightMs`, `mon_durationMs`, and the same pair for `tue` to `sun` | integer or null | When the popup may show on that weekday: the start, in milliseconds after midnight, and the length. The server doesn't check them; the web reads them in the browser's local time (`marketing-popup.service.ts:56-67`)                                                                                                                                                                                                                          |

## Notification settings object

The caller's switches in [GET /user-notification-settings](#get-user-notification-settings): the columns of [`tPri_UserNotifSettings`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_usernotifsettings.md), each `1` (on) or `0` (off) (apipy @ 0e83c85e5a, `model/feature_notification.py:2227-2300`). The [sender](#push-delivery) reads the same names from each device row's copy, which [POST /fbu\_devicetoken](#post-fbu_devicetoken) keeps in step.

| Field                                                                                        | Type    | Meaning                                                                                                                                                                                                                                                                                                                       |
| -------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fAllNotifications`                                                                          | integer | All notifications. The apps also send it as the device row's `notifications` flag, which the sender reads (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/FirebaseTokenUtils.java:58`; ios @ aa31967ac8, `SVProgressHUD/FCMHelper.swift:1710`; apipy @ 0e83c85e5a, `model/feature_notification.py:2538`) |
| `fFirebaseChatCreated`                                                                       | integer | Chat tab pushes. apipy's sender doesn't read it; the Laravel chat push route drops receivers who have it at 0 ([Chat](https://docs.snapfix.com/engineering-reference/api/chat.md#post-v1appnotificationsend))                                                                                                                 |
| `fJobCreated`, `fJobAssignedToMe`, `fChatCreated`, `fJobReminderActivated`, `fTodoCompleted` | integer | New tasks, tasks assigned to the user, task chat messages, reminders, and checklists completed: push types 6, 44, 1, 58 and 73 (`model/feature_notification.py:2552-2592`)                                                                                                                                                    |
| `fStatusJobCreatedByMe`, `fStatusJobAssignedtoMe`, `fStatusAllOtherJob`                      | integer | Status changes on tasks the user created, on tasks assigned to the user, and on all other tasks (`:2683-2785`)                                                                                                                                                                                                                |
| `fPriorityJobCreatedByMe`, `fPriorityJobAssignedtoMe`, `fPriorityJobAllOther`                | integer | Changes to priority tasks, in the same three groups (`:2593-2681`)                                                                                                                                                                                                                                                            |
| `fOtherNotifications`                                                                        | integer | Always `0` in this answer, whatever the row holds (`:2294`)                                                                                                                                                                                                                                                                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/engineering-reference/api/notifications.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
