> 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/staff.md).

# Staff 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/staff.md).
{% endhint %}

Tools for Snapfix staff: the admin API and the admin actions behind webadmin\_angular, company metrics, CRM and accounting links, logs, and the server dashboards. The admin app's pages are in [Staff screens](https://docs.snapfix.com/how-the-apps-work/screens/staff.md).

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/admin`, `/log-viewer`, Horizon); `php-apis` at `https://z1.snapfix.com`: actions at `/api/snapfix/index.php?action=<name>`, pages at their own path; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`; `apipy` at `https://z2.snapfix.com`; `authpy` at `https://z3.snapfix.com`. The admin app puts `/v1/admin/` in front of every api\_php\_live\_v2 path, sends JSON bodies, and adds the header `fOrigin: webadmin` to every request (webadmin\_angular @ db972390b8, `src/app/services/http/http.service.ts:61-71`, `src/app/services/auth/auth-interceptor/auth.interceptor.ts:100-106`).
* **Auth:**
  * **api\_php\_live\_v2 `/v1/admin`:** admin token: `Authorization: Bearer` with an access token that passes the HS256 check against `ADMIN_JWT_SECRET`. Its user must exist, must not be deleted, and must have the staff flag `fSnapfixWebAdminUser` (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Middleware/AuthorizeAdminApi.php:43-62`, `app/Services/JwtAuthService.php:29-33`, `app/Http/Middleware/WebAdmin.php:23`). Those are the only checks: any staff user may call any route, on any record. The admin app signs in with authpy's `POST /login` and sends that access token here (webadmin\_angular @ db972390b8, `src/app/services/auth/auth.service.ts:27-28`, `src/app/services/auth/auth-interceptor/auth.interceptor.ts:28-42`), so `ADMIN_JWT_SECRET` must hold the same value as authpy's signing key. The values are in no repo \[[ASK-202](https://github.com/snapfix/docs/blob/main/ASK.md#ask-202-does-the-laravel-admin-api-check-tokens-with-the-key-that-authpy-signs-them-with)]. Staff rights then rest on the sign-in token and the one flag \[[ASK-202](https://github.com/snapfix/docs/blob/main/ASK.md#ask-202-does-the-laravel-admin-api-check-tokens-with-the-key-that-authpy-signs-them-with)]. The group skips the checks that the `/v1/app` routes run: revoked tokens, temporary passwords, verification, the blacklist and the rate limits (`app/Providers/RouteServiceProvider.php:37-59`).
  * **Horizon and the log viewer page:** the internal Basic login (`config/horizon.php:73`, `config/log-viewer.php:74-77`). Horizon's own gate lets every caller through (`app/Providers/HorizonServiceProvider.php:24-25`). The log viewer's API has no middleware (`config/log-viewer.php:88-91`).
  * **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)]); actions use the `user_uuid` in the request, not the token's user; some actions take HTTP Basic with `AUTH_USERNAME` instead \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; the HubSpot callback needs no login. Only `create_temp_password`, `admin_parent_settings` and `admin_parent_settings_save` check that the token's user is Snapfix staff (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:27257-27261`, `htmlphp/api/snapfix/class/webapp.functions.php:9950-9955`, `:9982-9987`). The other actions here, the `admin_*` actions included, take any caller who passes the dispatcher.
  * **apipy:** user token (authpy JWT in `Authorization: Bearer`); nothing checks that the caller is Snapfix staff.
  * **authpy:** the Looker routes take the shared Basic login built into the apps. `/device` and `/user` take a user token whose user must be Snapfix staff (`fSnapfixWebAdminUser`); anyone else gets "unauthorised access" (authpy @ 5d5758661c, `app.py:1724-1765`, `model/feature_token_ops.py:751-754`, `:780-783`).
* **Used by:** webadmin\_angular (the staff admin app); authpy (the Looker actions of php-apis web). 194 of the 288 endpoints have no known caller: 135 of the 177 api\_php\_live\_v2, apipy and authpy rows, and 59 of the 111 php-apis rows. Of the 111 `/v1/admin` routes, 32 have a caller, all in the admin app.
* **Answers and errors:**
  * **api\_php\_live\_v2:** the envelope of [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses). No token: `401` "Token is not provided". An expired token, a bad signature or a token not yet valid: `401` with the token library's message. A token that is not an access token: `401` "Token is not valid". A token that cannot be read, a user that does not exist or is deleted, and a user without the staff flag: `400` "Something went wrong"; the real message, such as "Invalid user admin!", shows only with `APP_DEBUG` on. In a route: `404` "Resource not found" for an unknown or deleted record; `422` with the first failed rule's message; `400` with the message of a user error; `500` "An unexpected error occurred. Please try again later." for PHP and runtime errors, such as a database error; `400` "Something went wrong" for any other exception (`app/Exceptions/Handler.php:44-85`). Laravel writes a camelCase field name with spaces in its messages: `accountId` reads "account id". Only `X-API-Version` 1.0 reaches these handlers; another version answers `400` with the bare key `validation.version_mismatch` (`app/Http/Middleware/VersionControl.php:33-40`).
  * **apipy:** `200` with `result` `false` and the message for the errors a route catches; `401` "Access token expired" for an expired token; the token library's own answer, not the envelope, for a missing or unreadable token. apipy runs with Flask's testing mode on (apipy @ 0e83c85e5a, `app.py:105-106`), so an error that a route does not catch answers `500` from the web server, without a JSON body: the app's own 500 handler (`app.py:170-172`) does not run.
* **Logs:** api\_php\_live\_v2 writes each call to its request log. Only a top-level `password` field is masked, so nested passwords and fields such as `glPassword` are stored as sent (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/LogService.php:113`, `app/Helpers/common.php:589-598`). Responses under about 100 KB are kept too. An exception also writes the whole request to the error log (`app/Exceptions/Handler.php:96-105`). Every apipy call writes an abuse-check log row ([Blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).
* **SQL:** of the `/v1/admin` routes, only `GET /v1/admin/payment/paywall-parents` joins a request value into SQL: its `search` (`app/Services/ParentService.php:497`). apipy's staff lists put `offset`, `limit`, `sort_field` and filters into the SQL text.

| Method      | Path                                                                                                           | Service            | Purpose                                                                                                                                                                                                                                                                                                     |
| ----------- | -------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET         | `/log-viewer/...`                                                                                              | api\_php\_live\_v2 | Log viewer page (opcodesio/log-viewer) (no caller)                                                                                                                                                                                                                                                          |
| GET, DELETE | `/log-viewer/api/...`                                                                                          | api\_php\_live\_v2 | Log viewer API: reads and deletes the server logs (no caller)                                                                                                                                                                                                                                               |
| GET         | `/v1/admin/asset-reg`                                                                                          | api\_php\_live\_v2 | List asset registers (no caller)                                                                                                                                                                                                                                                                            |
| POST        | `/v1/admin/asset-reg`                                                                                          | api\_php\_live\_v2 | Create an asset register (no caller)                                                                                                                                                                                                                                                                        |
| POST        | `/v1/admin/asset-reg/copy`                                                                                     | api\_php\_live\_v2 | Copy an asset register (no caller)                                                                                                                                                                                                                                                                          |
| POST        | `/v1/admin/asset-reg/multiple`                                                                                 | api\_php\_live\_v2 | Create several asset registers (no caller)                                                                                                                                                                                                                                                                  |
| POST        | `/v1/admin/asset-reg/restore/{uuid}`                                                                           | api\_php\_live\_v2 | Restore a deleted asset register (no caller)                                                                                                                                                                                                                                                                |
| PUT         | `/v1/admin/asset-reg/{uuid}`                                                                                   | api\_php\_live\_v2 | Change an asset register (no caller)                                                                                                                                                                                                                                                                        |
| DELETE      | `/v1/admin/asset-reg/{uuid}`                                                                                   | api\_php\_live\_v2 | Delete an asset register (no caller)                                                                                                                                                                                                                                                                        |
| POST        | `/v1/admin/assets/multiple`                                                                                    | api\_php\_live\_v2 | Create several assets with attributes (no caller)                                                                                                                                                                                                                                                           |
| GET         | `/v1/admin/blacklist`                                                                                          | api\_php\_live\_v2 | List block list entries (no caller)                                                                                                                                                                                                                                                                         |
| POST        | `/v1/admin/blacklist`                                                                                          | api\_php\_live\_v2 | Create a block list entry (no caller)                                                                                                                                                                                                                                                                       |
| PUT         | `/v1/admin/blacklist/{uuid}`                                                                                   | api\_php\_live\_v2 | Change a block list entry (no caller)                                                                                                                                                                                                                                                                       |
| DELETE      | `/v1/admin/blacklist/{uuid}`                                                                                   | api\_php\_live\_v2 | Delete a block list entry (no caller)                                                                                                                                                                                                                                                                       |
| GET         | `/v1/admin/businesses`                                                                                         | api\_php\_live\_v2 | List groups (no caller)                                                                                                                                                                                                                                                                                     |
| POST        | `/v1/admin/businesses`                                                                                         | api\_php\_live\_v2 | Create a group (no caller)                                                                                                                                                                                                                                                                                  |
| POST        | `/v1/admin/businesses/copy`                                                                                    | api\_php\_live\_v2 | Copy a group (no caller)                                                                                                                                                                                                                                                                                    |
| POST        | `/v1/admin/businesses/multiple`                                                                                | api\_php\_live\_v2 | Create several groups (no caller)                                                                                                                                                                                                                                                                           |
| POST        | `/v1/admin/businesses/restore/{uuid}`                                                                          | api\_php\_live\_v2 | Restore a deleted group (no caller)                                                                                                                                                                                                                                                                         |
| GET         | `/v1/admin/businesses/templates`                                                                               | api\_php\_live\_v2 | List group templates (no caller)                                                                                                                                                                                                                                                                            |
| PUT         | `/v1/admin/businesses/{uuid}`                                                                                  | api\_php\_live\_v2 | Change a group (no caller)                                                                                                                                                                                                                                                                                  |
| DELETE      | `/v1/admin/businesses/{uuid}`                                                                                  | api\_php\_live\_v2 | Delete a group (no caller)                                                                                                                                                                                                                                                                                  |
| GET         | `/v1/admin/countries`                                                                                          | api\_php\_live\_v2 | List countries (no caller)                                                                                                                                                                                                                                                                                  |
| GET         | `/v1/admin/currencies`                                                                                         | api\_php\_live\_v2 | List currencies (no caller)                                                                                                                                                                                                                                                                                 |
| GET         | `/v1/admin/jobs`                                                                                               | api\_php\_live\_v2 | List tasks \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                                                                     |
| POST        | `/v1/admin/jobs/move`                                                                                          | api\_php\_live\_v2 | Move tasks (no caller)                                                                                                                                                                                                                                                                                      |
| POST        | `/v1/admin/jobs/multiple`                                                                                      | api\_php\_live\_v2 | Create several tasks (no caller)                                                                                                                                                                                                                                                                            |
| POST        | `/v1/admin/jobs/random`                                                                                        | api\_php\_live\_v2 | Create random tasks (no caller)                                                                                                                                                                                                                                                                             |
| POST        | `/v1/admin/jobs/soft-freeze`                                                                                   | api\_php\_live\_v2 | Soft-freeze tasks (no caller)                                                                                                                                                                                                                                                                               |
| POST        | `/v1/admin/jobs/validate-move`                                                                                 | api\_php\_live\_v2 | Check whether tasks can be moved (no caller)                                                                                                                                                                                                                                                                |
| GET         | `/v1/admin/marketing-popups`                                                                                   | api\_php\_live\_v2 | List marketing popups (no caller)                                                                                                                                                                                                                                                                           |
| POST        | `/v1/admin/marketing-popups`                                                                                   | api\_php\_live\_v2 | Create a marketing popup (no caller)                                                                                                                                                                                                                                                                        |
| GET         | `/v1/admin/marketing-popups/{uuid}`                                                                            | api\_php\_live\_v2 | Get a marketing popup (no caller)                                                                                                                                                                                                                                                                           |
| PUT         | `/v1/admin/marketing-popups/{uuid}`                                                                            | api\_php\_live\_v2 | Change a marketing popup (no caller)                                                                                                                                                                                                                                                                        |
| DELETE      | `/v1/admin/marketing-popups/{uuid}`                                                                            | api\_php\_live\_v2 | Delete a marketing popup (no caller)                                                                                                                                                                                                                                                                        |
| GET         | [`/v1/admin/organizations`](#get-v1adminorganizations)                                                         | api\_php\_live\_v2 | List organizations (`orgList`)                                                                                                                                                                                                                                                                              |
| POST        | [`/v1/admin/organizations`](#post-v1adminorganizations)                                                        | api\_php\_live\_v2 | Create an organization                                                                                                                                                                                                                                                                                      |
| GET         | [`/v1/admin/organizations/account/{name}`](#get-v1adminorganizationsaccountname)                               | api\_php\_live\_v2 | List organizations for an account name \[[ASK-211](https://github.com/snapfix/docs/blob/main/ASK.md#ask-211-should-the-hubspot-and-stripe-account-lists-hide-archived-or-inactive-rows)]                                                                                                                    |
| GET         | [`/v1/admin/organizations/{uuid}`](#get-v1adminorganizationsuuid)                                              | api\_php\_live\_v2 | Get an organization                                                                                                                                                                                                                                                                                         |
| PUT         | [`/v1/admin/organizations/{uuid}`](#put-v1adminorganizationsuuid)                                              | api\_php\_live\_v2 | Change an organization                                                                                                                                                                                                                                                                                      |
| DELETE      | [`/v1/admin/organizations/{uuid}`](#delete-v1adminorganizationsuuid)                                           | api\_php\_live\_v2 | Delete an organization                                                                                                                                                                                                                                                                                      |
| PUT         | [`/v1/admin/organizations/{uuid}/connect-account`](#put-v1adminorganizationsuuidconnect-account)               | api\_php\_live\_v2 | Connect an organization to an account                                                                                                                                                                                                                                                                       |
| PUT         | [`/v1/admin/organizations/{uuid}/disconnect-account`](#put-v1adminorganizationsuuiddisconnect-account)         | api\_php\_live\_v2 | Disconnect an organization from an account                                                                                                                                                                                                                                                                  |
| GET         | `/v1/admin/parents`                                                                                            | api\_php\_live\_v2 | List sites (no caller)                                                                                                                                                                                                                                                                                      |
| POST        | [`/v1/admin/parents`](#post-v1adminparents)                                                                    | api\_php\_live\_v2 | Create a site \[[ASK-77](https://github.com/snapfix/docs/blob/main/ASK.md#ask-77-who-should-be-recorded-as-the-creator-of-groups-users-and-sites-made-through-the-staff-admin-routes), [ASK-204](https://github.com/snapfix/docs/blob/main/ASK.md#ask-204-should-an-organization-have-one-site-or-several)] |
| POST        | `/v1/admin/parents/dashboard-stats`                                                                            | api\_php\_live\_v2 | Dashboard stats for sites (no caller)                                                                                                                                                                                                                                                                       |
| POST        | `/v1/admin/parents/guest-line-login`                                                                           | api\_php\_live\_v2 | Sign in to Guestline for a site (no caller)                                                                                                                                                                                                                                                                 |
| POST        | `/v1/admin/parents/onboard`                                                                                    | api\_php\_live\_v2 | Onboard a site (no caller)                                                                                                                                                                                                                                                                                  |
| POST        | `/v1/admin/parents/save-user`                                                                                  | api\_php\_live\_v2 | Save a site user (no caller)                                                                                                                                                                                                                                                                                |
| POST        | `/v1/admin/parents/users`                                                                                      | api\_php\_live\_v2 | List site users (no caller)                                                                                                                                                                                                                                                                                 |
| GET         | `/v1/admin/parents/{sessionUuid}/guest-line-statuses`                                                          | api\_php\_live\_v2 | Get the Guestline statuses of a session (no caller)                                                                                                                                                                                                                                                         |
| GET         | [`/v1/admin/parents/{uuid}`](#get-v1adminparentsuuid)                                                          | api\_php\_live\_v2 | Get a site                                                                                                                                                                                                                                                                                                  |
| PUT         | `/v1/admin/parents/{uuid}`                                                                                     | api\_php\_live\_v2 | Change a site (no caller)                                                                                                                                                                                                                                                                                   |
| DELETE      | `/v1/admin/parents/{uuid}`                                                                                     | api\_php\_live\_v2 | Delete a site (no caller)                                                                                                                                                                                                                                                                                   |
| POST        | `/v1/admin/parents/{uuid}/chat-kpi`                                                                            | api\_php\_live\_v2 | Get a site's chat KPI (no caller)                                                                                                                                                                                                                                                                           |
| PUT         | [`/v1/admin/parents/{uuid}/connect-organization`](#put-v1adminparentsuuidconnect-organization)                 | api\_php\_live\_v2 | Connect a site to an organization                                                                                                                                                                                                                                                                           |
| PUT         | [`/v1/admin/parents/{uuid}/disconnect-organization`](#put-v1adminparentsuuiddisconnect-organization)           | api\_php\_live\_v2 | Disconnect a site from an organization                                                                                                                                                                                                                                                                      |
| GET         | `/v1/admin/parents/{uuid}/geo-stats`                                                                           | api\_php\_live\_v2 | Get a site's location stats (no caller)                                                                                                                                                                                                                                                                     |
| GET         | `/v1/admin/parents/{uuid}/guest-line`                                                                          | api\_php\_live\_v2 | Get a site's Guestline settings (no caller)                                                                                                                                                                                                                                                                 |
| PUT         | `/v1/admin/parents/{uuid}/guest-line`                                                                          | api\_php\_live\_v2 | Change a site's Guestline settings (no caller)                                                                                                                                                                                                                                                              |
| GET         | `/v1/admin/payment/bundles`                                                                                    | api\_php\_live\_v2 | List marketing bundles (no caller)                                                                                                                                                                                                                                                                          |
| GET         | `/v1/admin/payment/packages`                                                                                   | api\_php\_live\_v2 | List packages (no caller)                                                                                                                                                                                                                                                                                   |
| POST        | `/v1/admin/payment/packages`                                                                                   | api\_php\_live\_v2 | Create a package (no caller)                                                                                                                                                                                                                                                                                |
| GET         | `/v1/admin/payment/paywall-packages`                                                                           | api\_php\_live\_v2 | List paywall packages (no caller)                                                                                                                                                                                                                                                                           |
| POST        | `/v1/admin/payment/paywall-packages`                                                                           | api\_php\_live\_v2 | Create a paywall package (no caller)                                                                                                                                                                                                                                                                        |
| PUT         | `/v1/admin/payment/paywall-packages/{uuid}`                                                                    | api\_php\_live\_v2 | Change a paywall package (no caller)                                                                                                                                                                                                                                                                        |
| GET         | `/v1/admin/payment/paywall-parents`                                                                            | api\_php\_live\_v2 | List sites' paywall settings (no caller)                                                                                                                                                                                                                                                                    |
| PUT         | `/v1/admin/payment/paywall-parents`                                                                            | api\_php\_live\_v2 | Change sites' paywall settings (no caller)                                                                                                                                                                                                                                                                  |
| POST        | `/v1/admin/public-simple-api`                                                                                  | api\_php\_live\_v2 | Create a public API key (no caller)                                                                                                                                                                                                                                                                         |
| GET         | [`/v1/admin/qr-form`](#get-v1adminqr-form)                                                                     | api\_php\_live\_v2 | List QR forms                                                                                                                                                                                                                                                                                               |
| POST        | [`/v1/admin/qr-form`](#post-v1adminqr-form)                                                                    | api\_php\_live\_v2 | Create a QR form                                                                                                                                                                                                                                                                                            |
| PUT         | [`/v1/admin/qr-form/{uuid}`](#put-v1adminqr-formuuid)                                                          | api\_php\_live\_v2 | Change a QR form                                                                                                                                                                                                                                                                                            |
| DELETE      | [`/v1/admin/qr-form/{uuid}`](#delete-v1adminqr-formuuid)                                                       | api\_php\_live\_v2 | Delete a QR form                                                                                                                                                                                                                                                                                            |
| GET         | `/v1/admin/rate-limit`                                                                                         | api\_php\_live\_v2 | List rate limits (no caller)                                                                                                                                                                                                                                                                                |
| POST        | `/v1/admin/rate-limit`                                                                                         | api\_php\_live\_v2 | Create a rate limit (no caller)                                                                                                                                                                                                                                                                             |
| GET         | `/v1/admin/rate-limit/disable`                                                                                 | api\_php\_live\_v2 | Turn rate limiting off (no caller)                                                                                                                                                                                                                                                                          |
| GET         | `/v1/admin/rate-limit/enable`                                                                                  | api\_php\_live\_v2 | Turn rate limiting on (no caller)                                                                                                                                                                                                                                                                           |
| PUT         | `/v1/admin/rate-limit/{uuid}`                                                                                  | api\_php\_live\_v2 | Change a rate limit (no caller)                                                                                                                                                                                                                                                                             |
| DELETE      | `/v1/admin/rate-limit/{uuid}`                                                                                  | api\_php\_live\_v2 | Delete a rate limit (no caller)                                                                                                                                                                                                                                                                             |
| POST        | [`/v1/admin/sales/company-gocardless-checkout`](#post-v1adminsalescompany-gocardless-checkout)                 | api\_php\_live\_v2 | Start a GoCardless checkout for a company                                                                                                                                                                                                                                                                   |
| POST        | [`/v1/admin/sales/company-stripe-checkout`](#post-v1adminsalescompany-stripe-checkout)                         | api\_php\_live\_v2 | Start a Stripe checkout for a company \[[ASK-210](https://github.com/snapfix/docs/blob/main/ASK.md#ask-210-should-a-stripe-checkout-skip-products-that-have-no-stripe-product)]                                                                                                                             |
| GET         | [`/v1/admin/sales/company-subscriptions/{companyId}`](#get-v1adminsalescompany-subscriptionscompanyid)         | api\_php\_live\_v2 | List a company's subscriptions                                                                                                                                                                                                                                                                              |
| GET         | [`/v1/admin/sales/deals`](#get-v1adminsalesdeals)                                                              | api\_php\_live\_v2 | List HubSpot deals                                                                                                                                                                                                                                                                                          |
| GET         | [`/v1/admin/sales/deals/{objectId}`](#get-v1adminsalesdealsobjectid)                                           | api\_php\_live\_v2 | Get a HubSpot deal                                                                                                                                                                                                                                                                                          |
| GET         | [`/v1/admin/sales/gocardless-customer`](#get-v1adminsalesgocardless-customer)                                  | api\_php\_live\_v2 | Get a GoCardless customer \[[ASK-209](https://github.com/snapfix/docs/blob/main/ASK.md#ask-209-should-a-failed-mandate-lookup-show-as-no-active-mandate)]                                                                                                                                                   |
| POST        | [`/v1/admin/sales/gocardless-customer-mandate`](#post-v1adminsalesgocardless-customer-mandate)                 | api\_php\_live\_v2 | Create a GoCardless mandate sign-up link for a customer                                                                                                                                                                                                                                                     |
| POST        | [`/v1/admin/sales/gocardless-payments`](#post-v1adminsalesgocardless-payments)                                 | api\_php\_live\_v2 | Get GoCardless payments                                                                                                                                                                                                                                                                                     |
| POST        | [`/v1/admin/sales/onboarding`](#post-v1adminsalesonboarding)                                                   | api\_php\_live\_v2 | Save a sales onboarding record                                                                                                                                                                                                                                                                              |
| GET         | [`/v1/admin/sales/stripe-customer`](#get-v1adminsalesstripe-customer)                                          | api\_php\_live\_v2 | Get a Stripe customer                                                                                                                                                                                                                                                                                       |
| GET         | [`/v1/admin/survey`](#get-v1adminsurvey)                                                                       | api\_php\_live\_v2 | List pre-registration surveys                                                                                                                                                                                                                                                                               |
| POST        | [`/v1/admin/survey`](#post-v1adminsurvey)                                                                      | api\_php\_live\_v2 | Create a pre-registration survey                                                                                                                                                                                                                                                                            |
| PUT         | [`/v1/admin/survey/{uuid}`](#put-v1adminsurveyuuid)                                                            | api\_php\_live\_v2 | Change a pre-registration survey                                                                                                                                                                                                                                                                            |
| DELETE      | [`/v1/admin/survey/{uuid}`](#delete-v1adminsurveyuuid)                                                         | api\_php\_live\_v2 | Delete a pre-registration survey                                                                                                                                                                                                                                                                            |
| PUT         | `/v1/admin/tags`                                                                                               | api\_php\_live\_v2 | Change tags (no caller)                                                                                                                                                                                                                                                                                     |
| GET         | `/v1/admin/tags/tag-headers`                                                                                   | api\_php\_live\_v2 | List tag folders (no caller)                                                                                                                                                                                                                                                                                |
| GET         | `/v1/admin/timezones`                                                                                          | api\_php\_live\_v2 | List time zones (no caller)                                                                                                                                                                                                                                                                                 |
| PUT         | `/v1/admin/todos`                                                                                              | api\_php\_live\_v2 | Change checklist items (no caller)                                                                                                                                                                                                                                                                          |
| POST        | `/v1/admin/upload`                                                                                             | api\_php\_live\_v2 | Upload a file (no caller)                                                                                                                                                                                                                                                                                   |
| GET         | `/v1/admin/user-relations`                                                                                     | api\_php\_live\_v2 | List user relations (no caller)                                                                                                                                                                                                                                                                             |
| POST        | `/v1/admin/user-relations`                                                                                     | api\_php\_live\_v2 | Create a user relation (no caller)                                                                                                                                                                                                                                                                          |
| PUT         | `/v1/admin/user-relations`                                                                                     | api\_php\_live\_v2 | Change a user relation (no caller)                                                                                                                                                                                                                                                                          |
| DELETE      | `/v1/admin/user-relations`                                                                                     | api\_php\_live\_v2 | Delete a user relation (no caller)                                                                                                                                                                                                                                                                          |
| POST        | `/v1/admin/user-relations/check-relation`                                                                      | api\_php\_live\_v2 | Check a user's relation (no caller)                                                                                                                                                                                                                                                                         |
| POST        | [`/v1/admin/user-relations/multiple`](#post-v1adminuser-relationsmultiple)                                     | api\_php\_live\_v2 | Add users to several groups, creating the users that don't exist yet \[[ASK-77](https://github.com/snapfix/docs/blob/main/ASK.md#ask-77-who-should-be-recorded-as-the-creator-of-groups-users-and-sites-made-through-the-staff-admin-routes)]                                                               |
| PUT         | [`/v1/admin/user-relations/multiple`](#put-v1adminuser-relationsmultiple)                                      | api\_php\_live\_v2 | Change the permissions of several members of one group                                                                                                                                                                                                                                                      |
| POST        | `/v1/admin/user-relations/restore`                                                                             | api\_php\_live\_v2 | Restore a deleted user relation (no caller)                                                                                                                                                                                                                                                                 |
| GET         | `/v1/admin/users`                                                                                              | api\_php\_live\_v2 | List users (no caller)                                                                                                                                                                                                                                                                                      |
| POST        | `/v1/admin/users`                                                                                              | api\_php\_live\_v2 | Create a user \[[ASK-77](https://github.com/snapfix/docs/blob/main/ASK.md#ask-77-who-should-be-recorded-as-the-creator-of-groups-users-and-sites-made-through-the-staff-admin-routes)] (no caller)                                                                                                          |
| DELETE      | `/v1/admin/users`                                                                                              | api\_php\_live\_v2 | Delete a user (no caller)                                                                                                                                                                                                                                                                                   |
| POST        | `/v1/admin/users/create-temp-password`                                                                         | api\_php\_live\_v2 | Create a temporary password for a user (no caller)                                                                                                                                                                                                                                                          |
| POST        | `/v1/admin/users/reset-password`                                                                               | api\_php\_live\_v2 | Reset a user's password \[[ASK-208](https://github.com/snapfix/docs/blob/main/ASK.md#ask-208-should-a-password-reset-by-staff-end-the-users-other-sessions)] (no caller)                                                                                                                                    |
| POST        | `/v1/admin/users/restore`                                                                                      | api\_php\_live\_v2 | Restore a deleted user (no caller)                                                                                                                                                                                                                                                                          |
| PUT         | `/v1/admin/users/{uuid}`                                                                                       | api\_php\_live\_v2 | Change a user (no caller)                                                                                                                                                                                                                                                                                   |
| GET, POST   | `/{horizon-path}/...`                                                                                          | api\_php\_live\_v2 | Laravel Horizon: queue dashboard and its API (no caller)                                                                                                                                                                                                                                                    |
| ANY         | `/api/snapfix/hubspot_callback.php`                                                                            | php-apis           | HubSpot callback; logs each request to a file \[[ASK-196](https://github.com/snapfix/docs/blob/main/ASK.md#ask-196-is-the-hubspot-callback-page-still-hubspots-oauth-redirect)] (no caller)                                                                                                                 |
| POST        | [`?action=admin_check_user`](#post-actionadmin_check_user)                                                     | php-apis           | Find a user by email, mobile number or staff username, with the whole account row and the group membership                                                                                                                                                                                                  |
| ANY         | `?action=admin_copy_job_tag`                                                                                   | php-apis           | Copy task tags (no caller)                                                                                                                                                                                                                                                                                  |
| ANY         | `?action=admin_copy_job_todo`                                                                                  | php-apis           | Copy checklist items (no caller)                                                                                                                                                                                                                                                                            |
| ANY         | `?action=admin_copy_job_user`                                                                                  | php-apis           | Copy task users (no caller)                                                                                                                                                                                                                                                                                 |
| POST        | [`?action=admin_create_assets`](#post-actionadmin_create_assets)                                               | php-apis           | Create assets in one asset register, written after the answer (`initAdminCreateAssets`)                                                                                                                                                                                                                     |
| ANY         | `?action=admin_create_business_defaults`                                                                       | php-apis           | Create a group's defaults (no caller)                                                                                                                                                                                                                                                                       |
| ANY         | `?action=admin_create_businesses_v1`                                                                           | php-apis           | Create groups in bulk (v1) (no caller)                                                                                                                                                                                                                                                                      |
| POST        | [`?action=admin_create_businesses_v2`](#post-actionadmin_create_businesses_v2)                                 | php-apis           | Create groups in a site, with their defaults (v2)                                                                                                                                                                                                                                                           |
| POST        | [`?action=admin_create_checklist`](#post-actionadmin_create_checklist)                                         | php-apis           | Replace a task's checklist: the old items are deleted first                                                                                                                                                                                                                                                 |
| POST        | [`?action=admin_create_jobs`](#post-actionadmin_create_jobs)                                                   | php-apis           | Create tasks in a group, written after the answer (`initCreateJobs`)                                                                                                                                                                                                                                        |
| POST        | [`?action=admin_create_mkt_popup`](#post-actionadmin_create_mkt_popup)                                         | php-apis           | Create a marketing popup, shown to every site when no site is named                                                                                                                                                                                                                                         |
| POST        | [`?action=admin_create_package`](#post-actionadmin_create_package)                                             | php-apis           | Create a sales package for one site, with its Stripe products and prices                                                                                                                                                                                                                                    |
| ANY         | `?action=admin_create_pri_parent`                                                                              | php-apis           | Create a site (no caller)                                                                                                                                                                                                                                                                                   |
| POST        | [`?action=admin_create_stripe_product_v3`](#post-actionadmin_create_stripe_product_v3)                         | php-apis           | Create a sales package with its Stripe prices, and return its link (v3)                                                                                                                                                                                                                                     |
| POST        | [`?action=admin_dashboard_parents`](#post-actionadmin_dashboard_parents)                                       | php-apis           | Usage figures by site; without `parent_uuids`, every paying site                                                                                                                                                                                                                                            |
| POST        | [`?action=admin_delete_mkt_popup`](#post-actionadmin_delete_mkt_popup)                                         | php-apis           | Delete a marketing popup (`updateMarkettingPopup`)                                                                                                                                                                                                                                                          |
| ANY         | `?action=admin_delete_package`                                                                                 | php-apis           | Delete a package and switch off its Stripe products (no caller)                                                                                                                                                                                                                                             |
| ANY         | `?action=admin_delete_stripe_price_v3`                                                                         | php-apis           | Disabled: always answers with a fixed error (no caller)                                                                                                                                                                                                                                                     |
| ANY         | `?action=admin_delete_stripe_product_v3`                                                                       | php-apis           | Disabled: always answers with a fixed error (no caller)                                                                                                                                                                                                                                                     |
| ANY         | `?action=admin_duplicate_pri_tags`                                                                             | php-apis           | Copy tags (no caller)                                                                                                                                                                                                                                                                                       |
| ANY         | `?action=admin_duplicate_pri_user_business`                                                                    | php-apis           | Copy group memberships (no caller)                                                                                                                                                                                                                                                                          |
| ANY         | `?action=admin_edit_user_password`                                                                             | php-apis           | Change a user's password, found by email (no caller)                                                                                                                                                                                                                                                        |
| POST        | [`?action=admin_guestline_login`](#post-actionadmin_guestline_login)                                           | php-apis           | Send a Guestline login to Guestline and return its answer                                                                                                                                                                                                                                                   |
| POST        | [`?action=admin_guestline_statuses`](#post-actionadmin_guestline_statuses)                                     | php-apis           | Get a Guestline session's housekeeping codes from Guestline                                                                                                                                                                                                                                                 |
| POST        | [`?action=admin_list_mkt_popup`](#post-actionadmin_list_mkt_popup)                                             | php-apis           | List marketing popups                                                                                                                                                                                                                                                                                       |
| POST        | [`?action=admin_list_parent_user`](#post-actionadmin_list_parent_user)                                         | php-apis           | List a site's admins; without `parent_uuid`, every site's                                                                                                                                                                                                                                                   |
| POST        | [`?action=admin_mkt_popup_detail`](#post-actionadmin_mkt_popup_detail)                                         | php-apis           | Get a marketing popup                                                                                                                                                                                                                                                                                       |
| POST        | [`?action=admin_modify_gl_parent`](#post-actionadmin_modify_gl_parent)                                         | php-apis           | Change a site's Guestline settings, password included                                                                                                                                                                                                                                                       |
| POST        | [`?action=admin_modify_mkt_popup`](#post-actionadmin_modify_mkt_popup)                                         | php-apis           | Change a marketing popup                                                                                                                                                                                                                                                                                    |
| POST        | [`?action=admin_modify_parent`](#post-actionadmin_modify_parent)                                               | php-apis           | Change a site's name, customer type, dates and more; `fDeleted` `1` deletes it                                                                                                                                                                                                                              |
| ANY         | `?action=admin_modify_parent_uuid`                                                                             | php-apis           | Change a site's UUID and move its groups (no caller)                                                                                                                                                                                                                                                        |
| ANY         | `?action=admin_modify_stripe_product_v3`                                                                       | php-apis           | Disabled: always answers with a fixed error (no caller)                                                                                                                                                                                                                                                     |
| POST        | [`?action=admin_onboard_parent`](#post-actionadmin_onboard_parent)                                             | php-apis           | Onboard a site: create it, its groups and their users                                                                                                                                                                                                                                                       |
| ANY         | `?action=admin_onboard_parent_v2`                                                                              | php-apis           | Onboard a site (v2) (no caller)                                                                                                                                                                                                                                                                             |
| ANY         | `?action=admin_packages`                                                                                       | php-apis           | List packages (v3) (no caller)                                                                                                                                                                                                                                                                              |
| POST        | [`?action=admin_read_gl_parent`](#post-actionadmin_read_gl_parent)                                             | php-apis           | Get a site's Guestline settings and its Guestline admin                                                                                                                                                                                                                                                     |
| POST        | [`?action=admin_read_group_tag_settings`](#post-actionadmin_read_group_tag_settings)                           | php-apis           | Read a group's tag folders and their tags                                                                                                                                                                                                                                                                   |
| POST        | [`?action=admin_read_jobs`](#post-actionadmin_read_jobs)                                                       | php-apis           | Read a group's task headers (`adminReadBusinessJobHeaderData`)                                                                                                                                                                                                                                              |
| POST        | [`?action=admin_read_pri_business`](#post-actionadmin_read_pri_business)                                       | php-apis           | Read groups by UUID or by filters, admin version of the generic read                                                                                                                                                                                                                                        |
| ANY         | `?action=admin_read_pri_parent`                                                                                | php-apis           | Read sites by UUID, admin version of the generic read (no caller)                                                                                                                                                                                                                                           |
| ANY         | `?action=admin_read_pri_user`                                                                                  | php-apis           | Read users by UUID, admin version of the generic read (no caller)                                                                                                                                                                                                                                           |
| ANY         | `?action=admin_read_pri_user_business`                                                                         | php-apis           | Read group memberships by UUID (no caller)                                                                                                                                                                                                                                                                  |
| POST        | [`?action=admin_read_pri_user_business_v2`](#post-actionadmin_read_pri_user_business_v2)                       | php-apis           | Read the memberships of groups, with the members' contact details (v2)                                                                                                                                                                                                                                      |
| POST        | [`?action=admin_read_stripe_products_v3`](#post-actionadmin_read_stripe_products_v3)                           | php-apis           | List the sales bundle's packages with their prices (v3)                                                                                                                                                                                                                                                     |
| POST        | [`?action=admin_reset_user_password`](#post-actionadmin_reset_user_password)                                   | php-apis           | Set a user's password                                                                                                                                                                                                                                                                                       |
| POST        | [`?action=admin_save_parent_user`](#post-actionadmin_save_parent_user)                                         | php-apis           | Add, change or remove a site's users and their site role                                                                                                                                                                                                                                                    |
| POST        | [`?action=admin_save_user`](#post-actionadmin_save_user)                                                       | php-apis           | Add a user to a group, creating the account when needed                                                                                                                                                                                                                                                     |
| POST        | [`?action=admin_save_users`](#post-actionadmin_save_users)                                                     | php-apis           | Run admin\_save\_user for each row of a list                                                                                                                                                                                                                                                                |
| POST        | [`?action=admin_update_group_tag_settings`](#post-actionadmin_update_group_tag_settings)                       | php-apis           | Rename and empty a group's tag folders, and add tags                                                                                                                                                                                                                                                        |
| ANY         | `?action=create_pri_log`                                                                                       | php-apis           | Create log entries, generic table action (no caller)                                                                                                                                                                                                                                                        |
| POST        | [`?action=create_snapfix_package`](#post-actioncreate_snapfix_package)                                         | php-apis           | Create a paywall package with its Stripe prices                                                                                                                                                                                                                                                             |
| POST        | [`?action=create_temp_password`](#post-actioncreate_temp_password)                                             | php-apis           | Create a one-time temporary password for a user; staff only                                                                                                                                                                                                                                                 |
| ANY         | `?action=dashboard_stats`                                                                                      | php-apis           | Dashboard stats (v2) (no caller)                                                                                                                                                                                                                                                                            |
| ANY         | `?action=dashboard_stats_excel`                                                                                | php-apis           | Dashboard stats as Excel (no caller)                                                                                                                                                                                                                                                                        |
| ANY         | `?action=delete_pri_log`                                                                                       | php-apis           | Delete log entries, generic table action (no caller)                                                                                                                                                                                                                                                        |
| ANY         | `?action=download_packages`                                                                                    | php-apis           | Download packages (no caller)                                                                                                                                                                                                                                                                               |
| POST        | [`?action=job_geo_stats`](#post-actionjob_geo_stats)                                                           | php-apis           | Task positions of groups, for the analytics map                                                                                                                                                                                                                                                             |
| ANY         | `?action=kpi_active_users`                                                                                     | php-apis           | KPI: active users per group (no caller)                                                                                                                                                                                                                                                                     |
| ANY         | `?action=kpi_business_jobs_c_day`                                                                              | php-apis           | KPI: group day report (`metricsBusinessDayReport`) (no caller)                                                                                                                                                                                                                                              |
| ANY         | `?action=kpi_business_jobs_c_month`                                                                            | php-apis           | KPI: group month report (`metricsBusinessMonthReport`) (no caller)                                                                                                                                                                                                                                          |
| ANY         | `?action=kpi_business_jobs_c_week`                                                                             | php-apis           | KPI: group week report (`metricsBusinessWeekReport`) (no caller)                                                                                                                                                                                                                                            |
| ANY         | `?action=kpi_business_jobs_c_year`                                                                             | php-apis           | KPI: group year report (`metricsBusinessYearReport`) (no caller)                                                                                                                                                                                                                                            |
| ANY         | `?action=kpi_businesses`                                                                                       | php-apis           | KPI: groups (`metricsBusinesses`) (no caller)                                                                                                                                                                                                                                                               |
| ANY         | `?action=kpi_day`                                                                                              | php-apis           | KPI: group day report (`metricsBusinessDayReport`) (no caller)                                                                                                                                                                                                                                              |
| POST        | [`?action=kpi_job_chats_created_day`](#post-actionkpi_job_chats_created_day)                                   | php-apis           | KPI: task chat messages created per day                                                                                                                                                                                                                                                                     |
| ANY         | `?action=kpi_job_chats_created_day_xlsx`                                                                       | php-apis           | KPI: task chat messages created per day (Excel) (no caller)                                                                                                                                                                                                                                                 |
| ANY         | `?action=kpi_job_chats_created_day_xlsx_v2`                                                                    | php-apis           | KPI: task chat messages created per day (Excel, v2) (no caller)                                                                                                                                                                                                                                             |
| ANY         | `?action=kpi_job_chats_created_day_xlsx_v2_fe`                                                                 | php-apis           | KPI: task chat messages created per day (Excel, v2, front-end version) (no caller)                                                                                                                                                                                                                          |
| POST        | [`?action=kpi_job_chats_created_day_xlsx_v2_webadmin`](#post-actionkpi_job_chats_created_day_xlsx_v2_webadmin) | php-apis           | KPI: task chat messages per day as a spreadsheet, for the CS dashboard (Excel, v2, admin app version)                                                                                                                                                                                                       |
| ANY         | `?action=kpi_jobs_created_day`                                                                                 | php-apis           | KPI: tasks created per day (no caller)                                                                                                                                                                                                                                                                      |
| ANY         | `?action=kpi_jobs_created_day_xlsx`                                                                            | php-apis           | KPI: tasks created per day (Excel) (no caller)                                                                                                                                                                                                                                                              |
| ANY         | `?action=kpi_month`                                                                                            | php-apis           | KPI: group month report (`metricsBusinessMonthReport`) (no caller)                                                                                                                                                                                                                                          |
| ANY         | `?action=kpi_user_job_chats_created_day_xlsx`                                                                  | php-apis           | KPI: task chat messages created per user per day (Excel) (no caller)                                                                                                                                                                                                                                        |
| ANY         | `?action=kpi_week`                                                                                             | php-apis           | KPI: group week report (`metricsBusinessWeekReport`) (no caller)                                                                                                                                                                                                                                            |
| ANY         | `?action=kpi_year`                                                                                             | php-apis           | KPI: yearly totals of a metric for the chosen customer types, this year and earlier years (`metricsBusinessYearReport`) (no caller)                                                                                                                                                                         |
| ANY         | `?action=log_backup`                                                                                           | php-apis           | Back up the API log; calls a method that does not exist (no caller)                                                                                                                                                                                                                                         |
| ANY         | `?action=log_network_data`                                                                                     | php-apis           | Save network log rows; takes the shared Basic login, not a token (no caller)                                                                                                                                                                                                                                |
| ANY         | `?action=log_read_data`                                                                                        | php-apis           | Read logged data; calls a method that does not exist (`logReadData`) (no caller)                                                                                                                                                                                                                            |
| ANY         | `?action=mdb_save_data`                                                                                        | php-apis           | Save a document into any MongoDB collection the request names (no caller)                                                                                                                                                                                                                                   |
| ANY         | `?action=mdb_save_login_data`                                                                                  | php-apis           | Save users' data to MongoDB; prints table sizes and stops, so nothing is saved (no caller)                                                                                                                                                                                                                  |
| POST        | [`?action=migrate_job_v1`](#post-actionmigrate_job_v1)                                                         | php-apis           | Move a task to another group of the same site: copy it, then mark the original deleted                                                                                                                                                                                                                      |
| POST        | [`?action=migrate_job_v1_validate`](#post-actionmigrate_job_v1_validate)                                       | php-apis           | Compare two groups before a task move (`findBusinessDifferencesV2`); names the task's people missing from the target                                                                                                                                                                                        |
| ANY         | `?action=modify_pri_log`                                                                                       | php-apis           | Change log entries, generic table action (no caller)                                                                                                                                                                                                                                                        |
| POST        | [`?action=paying_sales_trial_account_users_webadmin`](#post-actionpaying_sales_trial_account_users_webadmin)   | php-apis           | Report of the users of paying and sales-trial sites, as a public spreadsheet \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)]                                                |
| ANY         | `?action=read_pri_log`                                                                                         | php-apis           | Read log entries by UUID, generic table action; always answers "Access Restricted" (no caller)                                                                                                                                                                                                              |
| ANY         | `?action=read_s3_logs`                                                                                         | php-apis           | List the file names in the server log bucket (no caller)                                                                                                                                                                                                                                                    |
| ANY         | `?action=read_server_only_email_event`                                                                         | php-apis           | Read email events by UUID, generic table action (no caller)                                                                                                                                                                                                                                                 |
| ANY         | `?action=save_pri_log`                                                                                         | php-apis           | Save log entries, generic table action (no caller)                                                                                                                                                                                                                                                          |
| ANY         | `?action=save_server_only_email_event`                                                                         | php-apis           | Save email events, generic table action (no caller)                                                                                                                                                                                                                                                         |
| POST        | [`?action=snapfix_bundles`](#post-actionsnapfix_bundles)                                                       | php-apis           | List the paywall's marketing bundles                                                                                                                                                                                                                                                                        |
| POST        | [`?action=snapfix_packages`](#post-actionsnapfix_packages)                                                     | php-apis           | List paywall packages with their schema and prices                                                                                                                                                                                                                                                          |
| POST        | [`?action=update_package_schema`](#post-actionupdate_package_schema)                                           | php-apis           | Replace a package's paywall schema                                                                                                                                                                                                                                                                          |
| ANY         | `?action=user_log_read_data`                                                                                   | php-apis           | Export users' account data to a public file (no caller)                                                                                                                                                                                                                                                     |
| ANY         | `?action=user_log_read_data_sqlite`                                                                            | php-apis           | Export users' account data to a public SQLite file (no caller)                                                                                                                                                                                                                                              |
| ANY         | `?action=validate_email_admin`                                                                                 | php-apis           | Mark the email of the account with that address verified (no caller)                                                                                                                                                                                                                                        |
| ANY         | `?action=validate_mobile_admin`                                                                                | php-apis           | Mark the phone number of the account with that number verified (no caller)                                                                                                                                                                                                                                  |
| ANY         | `?action=admin_parent_settings`                                                                                | php-apis web       | Get a site's settings; staff only (no caller)                                                                                                                                                                                                                                                               |
| ANY         | `?action=admin_parent_settings_save`                                                                           | php-apis web       | Save a site's settings; staff only (no caller)                                                                                                                                                                                                                                                              |
| POST        | [`?action=looker_au_wow`](#post-actionlooker_au_wow)                                                           | php-apis web       | Looker metric for authpy: active users per site, week over week                                                                                                                                                                                                                                             |
| POST        | [`?action=looker_churnrate`](#post-actionlooker_churnrate)                                                     | php-apis web       | Looker metric for authpy: monthly churn rate, all sites                                                                                                                                                                                                                                                     |
| POST        | [`?action=looker_tc_wow`](#post-actionlooker_tc_wow)                                                           | php-apis web       | Looker metric for authpy: tasks created per site, week over week                                                                                                                                                                                                                                            |
| POST        | [`?action=looker_wau`](#post-actionlooker_wau)                                                                 | php-apis web       | Looker metric for authpy: weekly active users                                                                                                                                                                                                                                                               |
| POST        | [`?action=looker_wau_avg_median`](#post-actionlooker_wau_avg_median)                                           | php-apis web       | Looker metric for authpy: weekly average and median active users                                                                                                                                                                                                                                            |
| POST        | [`?action=looker_wau_percent`](#post-actionlooker_wau_percent)                                                 | php-apis web       | Looker metric for authpy: weekly active users, percent, per site                                                                                                                                                                                                                                            |
| POST        | [`?action=looker_wc_activity`](#post-actionlooker_wc_activity)                                                 | php-apis web       | Looker metric for authpy: weekly checklist activity per site                                                                                                                                                                                                                                                |
| POST        | [`?action=looker_wc_count`](#post-actionlooker_wc_count)                                                       | php-apis web       | Looker metric for authpy: weekly checklist count per site                                                                                                                                                                                                                                                   |
| POST        | [`?action=looker_wgau_percent`](#post-actionlooker_wgau_percent)                                               | php-apis web       | Looker metric for authpy: weekly generic active users, percent, per site                                                                                                                                                                                                                                    |
| POST        | [`?action=looker_wtc`](#post-actionlooker_wtc)                                                                 | php-apis web       | Looker metric for authpy: weekly tasks created                                                                                                                                                                                                                                                              |
| POST        | [`?action=looker_wtc_avg_median`](#post-actionlooker_wtc_avg_median)                                           | php-apis web       | Looker metric for authpy: weekly average and median tasks created                                                                                                                                                                                                                                           |
| ANY         | `?action=webcust_list_business_for_admin`                                                                      | php-apis web       | List the groups of the request's `user_uuid`, with that user's memberships and admin sites (`listAllRelevantBusiness`) (no caller)                                                                                                                                                                          |
| GET         | `/business-v5`                                                                                                 | apipy              | List groups (v5) (no caller)                                                                                                                                                                                                                                                                                |
| GET         | [`/cs-dashboard`](#get-cs-dashboard)                                                                           | apipy              | Customer support dashboard                                                                                                                                                                                                                                                                                  |
| GET         | [`/email-logs`](#get-email-logs)                                                                               | apipy              | List email logs                                                                                                                                                                                                                                                                                             |
| GET         | `/email-logs/{uuid}`                                                                                           | apipy              | Get an email log (no caller)                                                                                                                                                                                                                                                                                |
| GET         | `/hubspot-companies`                                                                                           | apipy              | List HubSpot companies (no caller)                                                                                                                                                                                                                                                                          |
| POST        | `/hubspot-company-parent`                                                                                      | apipy              | Link a HubSpot company to a site (no caller)                                                                                                                                                                                                                                                                |
| DELETE      | `/hubspot-company-parent`                                                                                      | apipy              | Unlink a HubSpot company from a site (no caller)                                                                                                                                                                                                                                                            |
| GET         | `/hubspot-company-parents`                                                                                     | apipy              | List links between HubSpot companies and sites (no caller)                                                                                                                                                                                                                                                  |
| POST        | `/hubspot-contact-parent`                                                                                      | apipy              | Link a HubSpot contact to a site (no caller)                                                                                                                                                                                                                                                                |
| DELETE      | `/hubspot-contact-parent`                                                                                      | apipy              | Unlink a HubSpot contact from a site (no caller)                                                                                                                                                                                                                                                            |
| GET         | `/hubspot-contact-parents`                                                                                     | apipy              | List links between HubSpot contacts and sites (no caller)                                                                                                                                                                                                                                                   |
| GET         | `/hubspot-contacts`                                                                                            | apipy              | List HubSpot contacts (no caller)                                                                                                                                                                                                                                                                           |
| GET         | `/logswebappadmin`                                                                                             | apipy              | List admin app logs (no caller)                                                                                                                                                                                                                                                                             |
| POST        | `/logwebappadmin`                                                                                              | apipy              | Create an admin app log entry; the form's values go into the SQL (no caller)                                                                                                                                                                                                                                |
| PUT         | `/logwebappadmin`                                                                                              | apipy              | Change an admin app log entry (no caller)                                                                                                                                                                                                                                                                   |
| DELETE      | `/logwebappadmin`                                                                                              | apipy              | Delete an admin app log entry (no caller)                                                                                                                                                                                                                                                                   |
| GET         | `/logwebappadmin/{uuid}`                                                                                       | apipy              | Get an admin app log entry (no caller)                                                                                                                                                                                                                                                                      |
| POST        | `/onboarding-code`                                                                                             | apipy              | Create an onboarding code (no caller)                                                                                                                                                                                                                                                                       |
| DELETE      | `/onboarding-code/{code}`                                                                                      | apipy              | Delete an onboarding code (no caller)                                                                                                                                                                                                                                                                       |
| GET         | `/onboarding-codes-v5`                                                                                         | apipy              | List onboarding codes (v5) (no caller)                                                                                                                                                                                                                                                                      |
| POST        | `/parent`                                                                                                      | apipy              | Create a site (no caller)                                                                                                                                                                                                                                                                                   |
| PUT         | `/parent`                                                                                                      | apipy              | Change a site (no caller)                                                                                                                                                                                                                                                                                   |
| DELETE      | `/parent`                                                                                                      | apipy              | Delete a site (no caller)                                                                                                                                                                                                                                                                                   |
| GET         | `/parent/{uuid}`                                                                                               | apipy              | Get a site (no caller)                                                                                                                                                                                                                                                                                      |
| GET         | `/parents`                                                                                                     | apipy              | List sites (no caller)                                                                                                                                                                                                                                                                                      |
| GET         | `/parents-v5`                                                                                                  | apipy              | List sites (v5) (no caller)                                                                                                                                                                                                                                                                                 |
| POST        | `/read-parent-data`                                                                                            | apipy              | Read site data; always fails on an undefined variable (no caller)                                                                                                                                                                                                                                           |
| GET         | [`/sms-logs`](#get-sms-logs)                                                                                   | apipy              | List SMS logs                                                                                                                                                                                                                                                                                               |
| GET         | `/sms-logs/{uuid}`                                                                                             | apipy              | Get an SMS log (no caller)                                                                                                                                                                                                                                                                                  |
| GET         | `/support-hours`                                                                                               | apipy              | List sites with support hours (no caller)                                                                                                                                                                                                                                                                   |
| GET         | [`/support-hours/{parent_uuid}`](#get-support-hoursparent_uuid)                                                | apipy              | Get a site's support hours                                                                                                                                                                                                                                                                                  |
| POST        | [`/support-hours/{parent_uuid}`](#post-support-hoursparent_uuid)                                               | apipy              | Add a site's support hours                                                                                                                                                                                                                                                                                  |
| PUT         | [`/support-hours/{parent_uuid}`](#put-support-hoursparent_uuid)                                                | apipy              | Change a site's support hours                                                                                                                                                                                                                                                                               |
| DELETE      | [`/support-hours/{parent_uuid}/{log_uuid}`](#delete-support-hoursparent_uuidlog_uuid)                          | apipy              | Delete a site's support hours entry                                                                                                                                                                                                                                                                         |
| GET         | `/v2/parents`                                                                                                  | apipy              | List sites (v2) (no caller)                                                                                                                                                                                                                                                                                 |
| GET         | [`/v4/parents`](#get-v4parents)                                                                                | apipy              | List sites (v4)                                                                                                                                                                                                                                                                                             |
| POST        | [`/v4/random-jobs`](#post-v4random-jobs)                                                                       | apipy              | Create random tasks                                                                                                                                                                                                                                                                                         |
| GET         | [`/v4/users`](#get-v4users)                                                                                    | apipy              | List users (v4)                                                                                                                                                                                                                                                                                             |
| POST        | `/xero-contact-parent`                                                                                         | apipy              | Link a Xero contact to a site (no caller)                                                                                                                                                                                                                                                                   |
| DELETE      | `/xero-contact-parent`                                                                                         | apipy              | Unlink a Xero contact from a site (no caller)                                                                                                                                                                                                                                                               |
| GET         | `/xero-contact-parents`                                                                                        | apipy              | List links between Xero contacts and sites (no caller)                                                                                                                                                                                                                                                      |
| GET         | `/xero-contacts`                                                                                               | apipy              | List Xero contacts (no caller)                                                                                                                                                                                                                                                                              |
| GET         | `/xero-sales-invoices`                                                                                         | apipy              | List Xero sales invoices (no caller)                                                                                                                                                                                                                                                                        |
| POST        | `/xero-sales-invoices-parent`                                                                                  | apipy              | Link a Xero sales invoice to a site (no caller)                                                                                                                                                                                                                                                             |
| DELETE      | `/xero-sales-invoices-parent`                                                                                  | apipy              | Unlink a Xero sales invoice from a site (no caller)                                                                                                                                                                                                                                                         |
| GET         | `/xero-sales-invoices-parents`                                                                                 | apipy              | List links between Xero sales invoices and sites (no caller)                                                                                                                                                                                                                                                |
| POST        | `/device`                                                                                                      | authpy             | Block devices; Snapfix staff only (no caller)                                                                                                                                                                                                                                                               |
| POST        | `/looker/au-wow`                                                                                               | authpy             | Looker metric, from php-apis: active users week over week \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                      |
| POST        | `/looker/churnrate-monthly`                                                                                    | authpy             | Looker metric, from php-apis: monthly churn rate \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                               |
| POST        | `/looker/tc-wow`                                                                                               | authpy             | Looker metric, from php-apis: tasks created week over week \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                     |
| POST        | `/looker/wau`                                                                                                  | authpy             | Looker metric, from php-apis: weekly active users \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                              |
| POST        | `/looker/wau-avg-median`                                                                                       | authpy             | Looker metric, from php-apis: weekly average and median active users \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                           |
| POST        | `/looker/wau-avg-median-sample`                                                                                | authpy             | Looker metric, from php-apis: weekly average and median active users, sample data only \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                         |
| POST        | `/looker/wau-percent`                                                                                          | authpy             | Looker metric, from php-apis: weekly active users, percent \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                     |
| POST        | `/looker/wau-sample`                                                                                           | authpy             | Looker metric, from php-apis: weekly active users, sample data only \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                            |
| POST        | `/looker/wc-activity`                                                                                          | authpy             | Looker metric, from php-apis: weekly checklist activity \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                        |
| POST        | `/looker/wc-count`                                                                                             | authpy             | Looker metric, from php-apis: weekly checklist count \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                           |
| POST        | `/looker/wgau-percent`                                                                                         | authpy             | Looker metric, from php-apis: weekly generic active users, percent \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                             |
| POST        | `/looker/wtc`                                                                                                  | authpy             | Looker metric, from php-apis: weekly tasks created \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                                             |
| POST        | `/looker/wtc-avg-median`                                                                                       | authpy             | Looker metric, from php-apis: weekly average and median tasks created \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                          |
| POST        | `/looker/wtc-avg-median-sample`                                                                                | authpy             | Looker metric, from php-apis: weekly average and median tasks created, sample data only \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                        |
| POST        | `/looker/wtc-sample`                                                                                           | authpy             | Looker metric, from php-apis: weekly tasks created, sample data only \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (no caller)                                                                                                           |
| POST        | `/user`                                                                                                        | authpy             | Block users; Snapfix staff only (no caller)                                                                                                                                                                                                                                                                 |

Notes on the table:

* Rows marked "(no caller)" have no call site in any client clone. webadmin\_angular is the only client of `/v1/admin`, and no repo calls authpy's `/looker/*` routes \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* The table has 288 rows; two of them name two methods (the log viewer API and Horizon).
* The action behind `POST /v1/admin/jobs/soft-freeze` is also mounted for scripts at `POST /v1/internal/tasks/soft-freeze`, behind the scripts login and without the staff check (api\_php\_live\_v2 @ ef3c4319f6, `routes/internal.php:28`, `:40`): see [Internal](https://docs.snapfix.com/engineering-reference/api/internal.md). Whether anything still calls it is not known \[[ASK-7](https://github.com/snapfix/docs/blob/main/ASK.md#ask-7-should-soft-freeze-still-run)].
* Site admins block users and devices through authpy's `POST /block-devices-v2` and `POST /block-users`: see [Users](https://docs.snapfix.com/engineering-reference/api/users.md).

## Org mapping service

The sales routes call the org mapping service (py-orgmapping, at `ORG_MAPPING_URL`, by default `https://orgmapping.snapfix.com`) with a Basic login from the server settings `ORG_MAPPING_USERNAME` and `ORG_MAPPING_PASSWORD`, which fall back to placeholder values when they are unset (api\_php\_live\_v2 @ ef3c4319f6, `config/app.php:331-333`, `app/Http/Controllers/v1/Versions/v1_0/Admin/OrgHubspotDealStateController.php:42-47`). The service's code is not in the repo set \[[ASK-6](https://github.com/snapfix/docs/blob/main/ASK.md#ask-6-confirm-these-repos-are-retired)], so its fields are given as this API reads them.

* A call fails when the HTTP status is an error or the answer has `status` `error`. The route then answers `400` with the service's `message`, or "Something went wrong" when there is none (`app/Services/OrgHubspotDealStateService.php:103-135`).
* Most answers pass the service's JSON through unchanged, so their fields are the service's. Each section names the fields the route adds and the fields the admin app reads.
* Values that go into the service's URLs (`currency`, `customerId`, `mandateId`) are not checked or encoded.

## GET /v1/admin/organizations

Lists every organization with the IDs of its linked accounts and its number of sites: the organization column of the mapping page.

* **Auth:** admin token (see the Auth line above). Every organization is listed.
* **Used by:** webadmin\_angular (`OrgMappingService.getOrganizationList`, from the organization column of the [Organization mapping](https://docs.snapfix.com/how-the-apps-work/screens/staff/org-mapping.md) page: webadmin\_angular @ db972390b8, `src/app/pages/org-mapping/org-mapping-orgs/org-mapping-orgs.component.ts:114`).

**Request:** none. The route reads no `limit`, `offset` or `sortBy`, so the list is not paged.

**Response** `200`: `data` is a list of [organization objects](#organization-object), in database order, with `parentsCount` filled. Deleted organizations are left out (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/OrgService.php:28-31`).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    { "uuid": "123", "name": "Riverside Group", "accounts": { "hubspot": "900", "stripe": null, "xero": null }, "parentsCount": 2 }
  ]
}
```

**Errors:** the admin token errors (see Answers and errors above).

**Side effects:** none.

## POST /v1/admin/organizations

Creates an organization from a name.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`OrgMappingService.createOrganization`, from the create dialog of the mapping page: `src/app/pages/org-mapping/create-org-modal/create-org-modal.component.ts:68`). The dialog then links the account or site it was opened for to the new organization (`:41-46`).

**Request** (JSON or form)

| Name   | In   | Type   | Required | Rules                                                     |
| ------ | ---- | ------ | -------- | --------------------------------------------------------- |
| `name` | body | string | yes      | Saved as `fName`. No length limit and no uniqueness check |

**Response** `200`: `data` is the new [organization detail object](#organization-detail-object), with `accounts` and `parents` empty. The message is the bare key `messages.org_created`, because the text is missing.

```json
{
  "status": "success",
  "message": "messages.org_created",
  "data": {
    "uuid": "123",
    "name": "Riverside Group",
    "image": null,
    "type": null,
    "address": null,
    "postalCode": null,
    "city": null,
    "country": null,
    "firstInvoiceDate": null,
    "nextRenewalDate": null,
    "subscriptionType": null,
    "accounts": [],
    "parents": []
  }
}
```

**Errors:** `422` "The name field is required." or "The name field must be a string."; the admin token errors.

**Side effects:** inserts a [`tPri_Org`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org.md) row, with the staff user as creator and modifier (`app/Traits/ModelUpdate.php:15-18`). Nothing else is written.

## GET /v1/admin/organizations/account/{name}

Lists the HubSpot, Stripe or Xero accounts that organizations can be linked to: one tab of the account column on the mapping page.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`OrgMappingService.getHsxList`, once per account type: `src/app/pages/org-mapping/org-mapping-hsx/org-mapping-hsx.component.ts:139`).

**Request**

| Name     | In    | Type   | Required | Rules                                                                                                                                        |
| -------- | ----- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | path  | string | yes      | `hubspot`, `stripe` or `xero`; another value gives `422` "The selected name is invalid."                                                     |
| `sortBy` | query | string | no       | `name`, `created` or `modified`; another value gives `422` "The selected sort by is invalid.". Checked, then not used: the list has no order |

**Response** `200`: `data` is a list of [organization account objects](#organization-account-object), in database order. The list is not paged.

* `hubspot`: every live row of [`tPri_Org_Hubspot`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_hubspot.md), one per HubSpot deal, archived deals included \[[ASK-211](https://github.com/snapfix/docs/blob/main/ASK.md#ask-211-should-the-hubspot-and-stripe-account-lists-hide-archived-or-inactive-rows)].
* `stripe`: every live row of [`tPri_Org_Stripe`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_stripe.md).
* `xero`: the live rows of [`tPri_Org_Xero`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_xero.md) that are customers and not suppliers (`app/Models/OrgXeroModel.php:63-69`).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [ { "uuid": "900", "accountId": "12345", "accountName": "Riverside Hotel renewal" } ]
}
```

**Errors:** `422` as above; the admin token errors.

**Side effects:** none.

## GET /v1/admin/organizations/{uuid}

Gets one organization with its linked accounts and its sites: the organization details dialog.

* **Auth:** admin token. Any organization by UUID.
* **Used by:** webadmin\_angular (`OrgMappingService.getOrganizationDetails`, from the details dialog: `src/app/pages/org-mapping/org-details-modal/org-details-modal.component.ts:157`).

**Request**

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

**Response** `200`: `data` is an [organization detail object](#organization-detail-object). Each site in `parents` is an [admin site object](#admin-site-object) without `parentAddress`; its counts are `0`, because they are not loaded.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "123",
    "name": "Riverside Group",
    "image": null,
    "type": null,
    "address": "1 Quay Street",
    "postalCode": "SW1A 1AA",
    "city": "London",
    "country": "GB",
    "firstInvoiceDate": null,
    "nextRenewalDate": null,
    "subscriptionType": null,
    "accounts": {
      "hubspot": { "uuid": "900", "accountId": "12345", "accountName": "Riverside Hotel renewal" }
    },
    "parents": [
      { "uuid": "401", "orgUuid": "123", "name": "Riverside Hotel", "image": null, "customerType": "paying_customer", "customerTypeTs": 1794387595000, "address": "1 Quay Street", "emailKey": null, "timezoneName": "Europe/London", "riskScore": null, "riskScoreTs": null, "firstInvoiceDateTs": null, "nextRenewalDateTs": null, "userCount": 0, "groupCount": 0, "jobCount": 0, "deleted": null, "createdTs": "2026-11-14T08:35:00.000000Z", "modifiedTs": "2026-11-14T08:35:00.000000Z" }
    ]
  }
}
```

**Errors:** `404` "Resource not found" for an unknown or deleted organization; the admin token errors.

**Side effects:** none.

## PUT /v1/admin/organizations/{uuid}

Renames an organization: the name field of the details dialog.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`OrgMappingService.updateOrganization`, from the details dialog: `src/app/pages/org-mapping/org-details-modal/org-details-modal.component.ts:48`).

**Request** (JSON or form)

| Name   | In   | Type   | Required | Rules            |
| ------ | ---- | ------ | -------- | ---------------- |
| `uuid` | path | string | yes      | The organization |
| `name` | body | string | yes      | Saved as `fName` |

**Response** `200`: `data` is the [organization object](#organization-object) after the change. `parentsCount` is `null`, because the count is not loaded. The message is the bare key `messages.org_updated`.

```json
{
  "status": "success",
  "message": "messages.org_updated",
  "data": { "uuid": "123", "name": "Riverside Group Ltd", "accounts": { "hubspot": "900", "stripe": null, "xero": null }, "parentsCount": null }
}
```

**Errors:** `422` "The name field is required." (checked first); `404` "Resource not found" for an unknown or deleted organization; the admin token errors.

**Side effects:** updates `fName`, `fModifiedTs`, `fServerTs` and the modifier, the staff user, on [`tPri_Org`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org.md) (`app/Traits/OrgUpdate.php:18-31`, `app/Traits/ModelUpdate.php:25-27`).

## DELETE /v1/admin/organizations/{uuid}

Deletes an organization and unlinks its sites: the Delete button of the details dialog, after a confirmation.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`OrgMappingService.deleteOrganization`, from the details dialog: `src/app/pages/org-mapping/org-details-modal/org-details-modal.component.ts:134`).

**Request**

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

**Response** `200`: `data` is `null`. The message is the bare key `messages.parent_deleted`, which is the site message and has no text either.

```json
{ "status": "success", "message": "messages.parent_deleted", "data": null }
```

**Errors:** `404` "Resource not found" for an unknown or deleted organization; the admin token errors.

**Side effects:** sets `uuid_tOrg` to `null` on each live site of the organization, one update per site, with no time log row. Then soft-deletes the organization: `fDeleted` 1 on [`tPri_Org`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org.md). Its linked account IDs stay on the deleted row (`app/Http/Controllers/v1/Versions/v1_0/Admin/OrgController.php:98-114`).

## PUT /v1/admin/organizations/{uuid}/connect-account

Links one HubSpot, Stripe or Xero account to an organization.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`OrgMappingService.connectHsxToOrg`: dropping an account on an organization on the mapping page, `src/app/pages/org-mapping/org-mapping.component.ts:132`, and the create dialog, `src/app/pages/org-mapping/create-org-modal/create-org-modal.component.ts:99`).

**Request** (JSON or form)

| Name          | In   | Type   | Required | Rules                                                                                                                                                                                                                                                                                                                                                             |
| ------------- | ---- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`        | path | string | yes      | The organization                                                                                                                                                                                                                                                                                                                                                  |
| `accountName` | body | string | yes      | `hubspot`, `stripe` or `xero`; another value gives "The selected account name is invalid."                                                                                                                                                                                                                                                                        |
| `accountId`   | body | string | yes      | The account row's `uuid`, as in an [organization account object](#organization-account-object). Saved in `uuid_tOrgHubspot`, `uuid_tOrgStripe` or `uuid_tOrgXero`. No live organization may hold it already, this one included: "The account ID is already connected to another organization." (`app/Rules/UniqueOrgAccountRule.php:17-32`). Not checked to exist |

**Response** `200`: `data` is the [organization object](#organization-object) after the change, with `parentsCount` `null`. The message is the bare key `messages.org_updated`.

**Errors:** `422` with the first failed rule's message, checked before the organization is read; `404` "Resource not found" for an unknown or deleted organization; the admin token errors.

**Side effects:** sets the account's column on [`tPri_Org`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org.md), with `fModifiedTs` and the staff user as modifier.

## PUT /v1/admin/organizations/{uuid}/disconnect-account

Unlinks one account from an organization: the remove button of an account in the details dialog, after a confirmation.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`OrgMappingService.disconnectHsxToOrg`, from the details dialog: `src/app/pages/org-mapping/org-details-modal/org-details-modal.component.ts:73`).

**Request** (JSON or form)

| Name          | In   | Type   | Required | Rules                                                                                                                                                                                             |
| ------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`        | path | string | yes      | The organization                                                                                                                                                                                  |
| `accountName` | body | string | yes      | `hubspot`, `stripe` or `xero`                                                                                                                                                                     |
| `accountId`   | body | string | yes      | Must be the account this organization holds for `accountName`; otherwise "The selected account id is invalid." (`app/Http/Requests/v1/Admin/Organization/DisconnectAccountFromOrgRequest.php:24`) |

**Response** `200`: `data` is the [organization object](#organization-object) after the change, with that account `null` and `parentsCount` `null`. The message is the bare key `messages.org_updated`.

**Errors:** `422` "The selected account id is invalid." when the organization does not hold that account, which is also the answer for an unknown organization, since the check runs first; `404` "Resource not found" only for a deleted organization that still holds the account; the admin token errors.

**Side effects:** sets that account's column to `null` on [`tPri_Org`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org.md).

## POST /v1/admin/parents

Creates a site with its basic address and its default settings.

* **Auth:** admin token. Nobody becomes a member of the new site.
* **Used by:** webadmin\_angular (`AccountService.createAccount`, from the account dialog: `src/app/pages/account/components/account-modal/account-modal.component.ts:72`). The dialog opens from the [Accounts](https://docs.snapfix.com/how-the-apps-work/screens/staff/accounts.md) page (`src/app/pages/account/account.component.ts:163`) and from the "Add Account" step of a deal on the [Hubspot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md) page (`src/app/pages/invoices/components/deal-account-modal/deal-account-modal.component.ts:30-46`). The app sends `name`, `address`, `timezoneName`, `customerType`, `state`, `city`, `postalCode` and `countryCode` (`src/app/services/account/account.service.ts:90-103`).

**Request** (JSON or form)

| Name                                                              | In   | Type   | Required        | Rules                                                                                                                                                                                                                                                                      |
| ----------------------------------------------------------------- | ---- | ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                                            | body | string | yes             | Saved as `fName` on the site and on its basic address. No uniqueness check \[[ASK-125](https://github.com/snapfix/docs/blob/main/ASK.md#ask-125-must-site-names-be-unique)]                                                                                                |
| `address`                                                         | body | string | yes             | Saved as `fAddress` on the site and as `fAddress1` on the basic address                                                                                                                                                                                                    |
| `customerType`                                                    | body | string | yes             | `paying_customer`, `sales_trial`, `churn`, `test`, `investor_probono` or `0`; another value gives "The selected customer type is invalid."                                                                                                                                 |
| `timezoneName`                                                    | body | string | yes             | A PHP time zone name, such as `Europe/London`. Saved as `timezone_name`                                                                                                                                                                                                    |
| `countryCode`                                                     | body | string | no              | Exactly 2 characters. Saved as `std_countries` on the site and on the address                                                                                                                                                                                              |
| `state`                                                           | body | string | no              | Nullable. Saved on the basic address only                                                                                                                                                                                                                                  |
| `city`, `postalCode`                                              | body | string | no              | Nullable. Saved as `fCity` and `fPostalCode` on the site and on the address                                                                                                                                                                                                |
| `orgUuid`                                                         | body | string | no              | Nullable. Saved as `uuid_tOrg`. No other site row, deleted rows included, may hold it: "The org uuid has already been taken." \[[ASK-204](https://github.com/snapfix/docs/blob/main/ASK.md#ask-204-should-an-organization-have-one-site-or-several)]. Not checked to exist |
| `origin`                                                          | body | string | no              | A value of `OriginType`, such as `web` or `web-admin`. When it is missing, the `fOrigin` request header is stored; the admin app sends `webadmin` there                                                                                                                    |
| `country`                                                         | body | string | no              | Saved as `fCountry` on the site                                                                                                                                                                                                                                            |
| `invoiceName`, `salesName`, `defaultCurrency`                     | body | string | no              | Saved as `fInvoiceName`, `fSalesName` and `default_currency`                                                                                                                                                                                                               |
| `emailKey`                                                        | body | string | no              | Must not be the email key of another live site: "Email key exists." Saved as `email_key`                                                                                                                                                                                   |
| `emailUserAdminUuid`                                              | body | string | with `emailKey` | A user's UUID that exists in [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md). Saved as `email_user_admin_uuid`                                                                                                                        |
| `stripeCustomerId`, `stripeVatId`, `stdNaicsCodes`, `stdUsecases` | body | string | no              | Saved as `stripe_customer_id`, `stripe_vat_id`, `std_naics_codes` and `std_usecases`                                                                                                                                                                                       |
| `stdCountries`                                                    | body | string | no              | Saved as `std_countries`, in place of `countryCode`                                                                                                                                                                                                                        |
| `customerTypeTs`                                                  | body | number | no              | Checked as a number, then not saved: the server sets the time itself                                                                                                                                                                                                       |

**Response** `200`: an [admin site object](#admin-site-object) with `parentAddress`. The message is "New Business created successfully"; no client shows it, because the admin app shows its own "Success" (`lang/en/messages.php:36`; webadmin\_angular @ db972390b8, `src/app/services/account/account.service.ts:102`, `src/app/services/http/http.service.ts:53`).

```json
{
  "status": "success",
  "message": "New Business created successfully",
  "data": {
    "uuid": "123",
    "orgUuid": null,
    "name": "Riverside Hotel",
    "image": null,
    "customerType": "paying_customer",
    "customerTypeTs": 1794387595000,
    "address": "1 Quay Street",
    "origin": "webadmin",
    "emailKey": null,
    "timezoneName": "Europe/London",
    "riskScore": null,
    "riskScoreTs": null,
    "firstInvoiceDateTs": null,
    "nextRenewalDateTs": null,
    "userCount": 0,
    "groupCount": 0,
    "jobCount": 0,
    "deleted": null,
    "createdTs": "2026-11-14T08:35:00.000000Z",
    "modifiedTs": "2026-11-14T08:35:00.000000Z",
    "parentAddress": { "uuid": "300", "name": "Riverside Hotel", "address1": "1 Quay Street", "address2": null, "postalCode": "SW1A 1AA", "city": "London", "state": null, "countryCode": "GB" }
  }
}
```

**Errors:** `422` with the first failed rule's message, for example "The name field is required."; the admin token errors.

**Side effects** (`app/Http/Controllers/v1/Versions/v1_0/Admin/ParentController.php:85-126`):

* Inserts a [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) row, with the staff user as creator and `fCustomerTypeTs` set to now (`app/Services/ParentService.php:339-344`).
* Inserts a [`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md) row and a basic [`tPri_ParentAddress`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentaddress.md) row, both with the staff user as creator.
* Inserts a [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md) row with chat on and the image, voice, video and document AI switches off, and the text `admin` as creator and modifier \[[ASK-77](https://github.com/snapfix/docs/blob/main/ASK.md#ask-77-who-should-be-recorded-as-the-creator-of-groups-users-and-sites-made-through-the-staff-admin-routes)].
* Queues a [`time_tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/time_tpri_parent.md) row, and a Firebase Realtime Database job that starts the site's package usage node.

## GET /v1/admin/parents/{uuid}

Gets one site with its basic address: the site name and address in a deal's dialogs.

* **Auth:** admin token. Any site by UUID.
* **Used by:** webadmin\_angular (`AccountService.getAccount`, from the deal dialog, `src/app/pages/invoices/components/deal-modal/deal-modal.component.ts:310`, and the onboarding link dialog, `src/app/pages/invoices/components/onboarding-url-modal/onboarding-url-modal.component.ts:54`, of the [Hubspot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md) page).

**Request**

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

**Response** `200`: an [admin site object](#admin-site-object) with `parentAddress`, in the shape of [POST /v1/admin/parents](#post-v1adminparents).

**Errors:** `404` "Resource not found" for an unknown or deleted site; the admin token errors.

**Side effects:** none.

## PUT /v1/admin/parents/{uuid}/connect-organization

Links a site to an organization.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`OrgMappingService.connectParentToOrg`: dropping a site on an organization on the mapping page, `src/app/pages/org-mapping/org-mapping.component.ts:195`, and the create dialog, `src/app/pages/org-mapping/create-org-modal/create-org-modal.component.ts:81`).

**Request** (JSON or form)

| Name      | In   | Type   | Required | Rules                                                                                                                                                                                                                                                                                   |
| --------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`    | path | string | yes      | The site                                                                                                                                                                                                                                                                                |
| `orgUuid` | body | string | yes      | Saved as `uuid_tOrg`. Not checked to exist or to be live. Several sites may share an organization here, though the create route allows one site per organization \[[ASK-204](https://github.com/snapfix/docs/blob/main/ASK.md#ask-204-should-an-organization-have-one-site-or-several)] |

**Response** `200`: the [admin site object](#admin-site-object) after the change, without `parentAddress`. The message is the bare key `messages.parent_updated`.

**Errors:** `422` "The org uuid field is required."; `404` "Resource not found" for an unknown or deleted site, checked after the body; the admin token errors.

**Side effects:** sets `uuid_tOrg`, `fModifiedTs`, `fServerTs` and the staff user as modifier on [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md), and queues a [`time_tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/time_tpri_parent.md) row (`app/Traits/ParentUpdate.php:25-56`).

## PUT /v1/admin/parents/{uuid}/disconnect-organization

Unlinks a site from its organization: the remove button of a site in the details dialog, after a confirmation.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`OrgMappingService.disconnectParentToOrg`, from the details dialog: `src/app/pages/org-mapping/org-details-modal/org-details-modal.component.ts:104`).

**Request** (JSON or form)

| Name      | In   | Type   | Required | Rules                                                                                                                                                       |
| --------- | ---- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`    | path | string | yes      | The site                                                                                                                                                    |
| `orgUuid` | body | string | yes      | Must be the site's current organization; otherwise "The selected org uuid is invalid." (`app/Http/Requests/v1/Admin/DisconnectParentFromOrgRequest.php:15`) |

**Response** `200`: the [admin site object](#admin-site-object) after the change, with `orgUuid` `null`. The message is the bare key `messages.parent_updated`.

**Errors:** `422` "The selected org uuid is invalid." when the site is not in that organization, which is also the answer for an unknown site, since the check runs first; `404` "Resource not found" only for a deleted site that is still linked; the admin token errors.

**Side effects:** sets `uuid_tOrg` to `null` on [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md), and queues a [`time_tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/time_tpri_parent.md) row.

## GET /v1/admin/qr-form

Lists the QR forms of one group, expired ones included: the [QR management](https://docs.snapfix.com/how-the-apps-work/screens/staff/qr-management.md) page for the selected group.

* **Auth:** admin token. Any group by UUID.
* **Used by:** webadmin\_angular (`QrManagementService.getQrList`, when a group is picked: `src/app/pages/qr-management/qr-management.component.ts:151`). After a delete the page removes the row itself and does not reload the list (`:161-172`).

**Request**

| Name           | In    | Type   | Required | Rules                                                                  |
| -------------- | ----- | ------ | -------- | ---------------------------------------------------------------------- |
| `businessUuid` | query | string | yes      | The group. A deleted group is found too; an asset register gives `404` |

**Response** `200`: `data` is a list of the group's live [QR form objects](#qr-form-object), in database order (`app/Http/Controllers/v1/Versions/v1_0/Admin/QrFormController.php:27-39`, `app/Services/QrFormService.php:27-37`).

**Errors:** `422` "The business uuid field is required."; `404` "Resource not found" for an unknown group; the admin token errors.

**Side effects:** none.

## POST /v1/admin/qr-form

Creates a QR form for a group. The group must have a live admin member.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`QrManagementService.saveQrForm`, from the QR form dialog when the form is new: `src/app/pages/qr-management/components/qr-management-modal/qr-management-modal.component.ts:98`). The app sends `businessUuid`, `formEnum`, the three titles, the hacker warning and its text, and `dynamicFormJson` with `page_form`, `page_success` and `page_fail`. It never sends `inAppVisible` or `hardcodedJobJson` (`src/app/services/qr-management/qr-management.service.ts:40-79`).

**Request** (JSON or form)

| Name                                             | In   | Type    | Required                          | Rules                                                                                                                                      |
| ------------------------------------------------ | ---- | ------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `businessUuid`                                   | body | string  | yes                               | A live group. Saved as `uuid_tBusiness`                                                                                                    |
| `dynamicFormJson`                                | body | object  | yes                               | The form's pages and components. Saved as `dynamic_form_json`, as sent                                                                     |
| `inAppTitle`, `posterTitle`, `posterDescription` | body | string  | yes                               | Saved as `in_app_title`, `poster_title` and `poster_description`                                                                           |
| `formEnum`                                       | body | string  | yes                               | `basic_v2`, `dropdown_v1`, `radiobutton_v1` or `dynamic_v1`; another value gives "The selected form enum is invalid." Saved as `form_enum` |
| `inAppVisible`                                   | body | integer | no                                | `0` or `1`; default `1`                                                                                                                    |
| `hardcodedJobJson`                               | body | object  | no                                | When it is missing, the server builds it for the group from schema version 1 (`resources/schemas/hardCodedJob.schema.v1.php`)              |
| `posterHackerWarning`                            | body | integer | yes                               | `0` or `1`                                                                                                                                 |
| `posterHackerWarningDescription`                 | body | string  | when `posterHackerWarning` is `1` | Nullable                                                                                                                                   |

**Response** `200`: `data` is the new [QR form object](#qr-form-object). The message is "QR form created successfully".

```json
{
  "status": "success",
  "message": "QR form created successfully",
  "data": {
    "uuid": "123",
    "businessUuid": "400",
    "dynamicFormJson": { "page_form": { "title": "Report a problem", "submit_button_text": "Send", "components": [] } },
    "inAppTitle": "Report a problem",
    "posterTitle": "Scan to report a problem",
    "posterDescription": "Room 101",
    "formEnum": "basic_v2",
    "posterHackerWarning": 0,
    "posterHackerWarningDescription": null,
    "createdTs": "2026-11-14T08:35:00Z",
    "modifiedTs": "2026-11-14T08:35:00Z",
    "createdByUserUuid": "200",
    "modifiedByUserUuid": "200"
  }
}
```

**Errors:** `422` with the first failed rule's message; `404` "Resource not found" for a group that does not exist or is deleted; `400` "The selected group does not have an admin assigned. Please add an admin to the group before creating the QR code." when the group has no live admin member (`app/Http/Controllers/v1/Versions/v1_0/Admin/QrFormController.php:58-67`); the admin token errors.

**Side effects:** inserts a [`qr_formdata`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata.md) row, with the staff user as creator.

## PUT /v1/admin/qr-form/{uuid}

Changes a QR form. The group cannot change.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`QrManagementService.saveQrForm`, from the QR form dialog when the form exists: `src/app/pages/qr-management/components/qr-management-modal/qr-management-modal.component.ts:98`, `src/app/services/qr-management/qr-management.service.ts:71-74`).

**Request** (JSON or form): the fields of [POST /v1/admin/qr-form](#post-v1adminqr-form) except `businessUuid`, all optional except these:

| Name                             | In   | Type    | Required                          | Rules                                                        |
| -------------------------------- | ---- | ------- | --------------------------------- | ------------------------------------------------------------ |
| `uuid`                           | path | string  | yes                               | The QR form                                                  |
| `posterHackerWarning`            | body | integer | yes                               | `0` or `1`                                                   |
| `posterHackerWarningDescription` | body | string  | when `posterHackerWarning` is `1` | Nullable                                                     |
| `formEnum`                       | body | string  | no                                | Any string: the type list of the create route is not applied |

**Response** `200`: the [QR form object](#qr-form-object) after the change. The message is "QR form updated successfully".

**Errors:** `422` with the first failed rule's message, checked first; `404` "Resource not found" for an unknown or deleted form; the admin token errors.

**Side effects:** updates the [`qr_formdata`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata.md) row, with the staff user as modifier.

## DELETE /v1/admin/qr-form/{uuid}

Deletes a QR form: the delete button of the QR management page, after a confirmation.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`QrManagementService.deleteQrItem`: `src/app/pages/qr-management/qr-management.component.ts:166`).

**Request**

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

**Response** `200`: `data` is `null`. The message is "QR form deleted successfully".

**Errors:** `404` "Resource not found" for an unknown or deleted form; the admin token errors.

**Side effects:** soft-deletes the [`qr_formdata`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata.md) row: `fDeleted` 1.

## POST /v1/admin/sales/company-gocardless-checkout

Starts a GoCardless payment for one line item of a deal, and records it: the bank payment of a line item in the deal dialog.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.createGocardlessCheckout`, from the line items of the deal dialog on the [Hubspot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md) page: `src/app/pages/invoices/components/deal-line-items/deal-line-items.component.ts:162`). The app sends the line item's amount times 100 as `productAmount`, and `one_off`, `monthly` or `yearly` as `productType`, from the line item's billing frequency (`src/app/services/invoice/invoice.service.ts:160-187`). It adds the answer to the deal's payment list.

**Request** (JSON or form)

| Name                            | In   | Type    | Required | Rules                                                            |
| ------------------------------- | ---- | ------- | -------- | ---------------------------------------------------------------- |
| `customerId`                    | body | string  | yes      | The GoCardless customer ID. Put into the org mapping URL as sent |
| `mandateId`                     | body | string  | yes      | The GoCardless mandate ID. Put into the org mapping URL as sent  |
| `dealId`, `itemId`, `companyId` | body | integer | yes      | The HubSpot deal, line item and company IDs                      |
| `productName`                   | body | string  | yes      | The line item's name                                             |
| `productAmount`                 | body | number  | yes      | The amount, passed on as sent                                    |
| `productCurrency`               | body | string  | yes      | The currency code, such as `GBP`                                 |
| `productType`                   | body | string  | yes      | Passed on as sent                                                |
| `parentUuid`                    | body | string  | no       | Nullable. The site, stored with the payment                      |

**Response** `200`: `data` is the [GoCardless payment](#gocardless-payment-object) that the org mapping service returns, passed through.

**Errors:** `422` with the first failed rule's message; `400` with the service's message when its call fails; the admin token errors.

**Side effects** (`app/Http/Controllers/v1/Versions/v1_0/Admin/OrgHubspotDealStateController.php:265-311`):

* Calls the service's `POST /gocardless/checkout/`, with the customer and mandate IDs in the query, and the product and the HubSpot IDs in the body.
* When it returns a payment, inserts a [`tPri_Org_GoCardlessPaymentLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_gocardlesspaymentlog.md) row with the site, deal, company, line item, customer, payment ID, dates, amount, product name, currency and mandate.

## POST /v1/admin/sales/company-stripe-checkout

Creates a Stripe checkout session for a deal's line items, and records its link: the card payment step of the deal dialog.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.createCheckout`, from the deal dialog: `src/app/pages/invoices/components/deal-modal/deal-modal.component.ts:189`). The app sends each line item's HubSpot product ID as `id`, its amount as `amount`, and `year`, `month` or an empty string as `interval`, from the billing frequency (`src/app/services/invoice/invoice.service.ts:77-108`).

**Request** (JSON or form)

| Name                               | In   | Type    | Required | Rules                                                                                                                                                                                                                                                    |
| ---------------------------------- | ---- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyId`, `contactId`, `dealId` | body | integer | yes      | The HubSpot company, contact and deal IDs                                                                                                                                                                                                                |
| `currency`                         | body | string  | yes      | The currency code of the prices                                                                                                                                                                                                                          |
| `products`                         | body | array   | yes      | One item per product. No maximum                                                                                                                                                                                                                         |
| `products.*.id`                    | body | integer | yes      | The HubSpot product ID; the service looks up the Stripe product for it. A product it does not find is left out \[[ASK-210](https://github.com/snapfix/docs/blob/main/ASK.md#ask-210-should-a-stripe-checkout-skip-products-that-have-no-stripe-product)] |
| `products.*.amount`                | body | number  | yes      | The price, passed on as sent                                                                                                                                                                                                                             |
| `products.*.interval`              | body | string  | no       | Nullable. `year`, `month` or empty                                                                                                                                                                                                                       |
| `parentUuid`                       | body | string  | no       | Nullable. The site, stored with the link and in the session's metadata. Send it, even as `null`: without the key, the call fails with `500` after the session is made, and no link is logged (`:385-386`)                                                |
| `startDate`                        | body | integer | no       | Nullable. Checked, then not used                                                                                                                                                                                                                         |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "checkoutSessionUrl": "https://checkout.example.com/pay/cs_123" }
}
```

**Errors:** `422` with the first failed rule's message; `400` with the service's message when a lookup or the session fails; the admin token errors.

**Side effects** (`app/Http/Controllers/v1/Versions/v1_0/Admin/OrgHubspotDealStateController.php:319-396`):

* Calls the service: the company's Stripe customer (`GET /stripe/customer/`), each product (`GET /stripe/product/{id}`), then `POST /stripe/checkout/` with the products, `trial_period_days` `0`, and the site and HubSpot IDs as metadata. When no product is found, the session is asked for with an empty product list \[[ASK-210](https://github.com/snapfix/docs/blob/main/ASK.md#ask-210-should-a-stripe-checkout-skip-products-that-have-no-stripe-product)].
* Inserts a [`tPri_Org_StripeCheckoutUrlLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_stripecheckouturllog.md) row with the site, deal, company, Stripe customer and link. The deal list counts these rows.

## GET /v1/admin/sales/company-subscriptions/{companyId}

Lists a company's Stripe subscriptions: the checkout history of the deal dialog.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.getCompanySubscriptions`, from the deal dialog: `src/app/pages/invoices/components/deal-modal/deal-modal.component.ts:326`). The app shows each subscription's `current_period_start` and `current_period_end`, in seconds, and its `currency`.

**Request**

| Name        | In   | Type    | Required | Rules                                                                                |
| ----------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------ |
| `companyId` | path | integer | yes      | The HubSpot company ID. No rule: a value that is not a whole number fails with `500` |

**Response** `200`: `data` is the list of subscriptions that the service returns, passed through, or `[]`.

**Errors:** `400` with the service's message when its call fails; `500` for a `companyId` that is not a whole number; the admin token errors.

**Side effects:** one call to the service's `GET /stripe/subscriptions/`. Writes nothing.

## GET /v1/admin/sales/deals

Lists the HubSpot deals that the org mapping service returns, each with its number of checkout links: the [Hubspot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md) page.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.getDeals`, when the page opens: `src/app/pages/invoices/invoices.component.ts:52`).

**Request:** none. The list is not paged: each call fetches every deal.

**Response** `200`: `data` is the service's list of deals, passed through. Each deal gets `checkoutUrlCount`: the number of Stripe checkout links logged with a company for the deal. Only deals that [`tPri_Org_HubspotDealState`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_hubspotdealstate.md) marks as won are counted; the others get `0` (`app/Services/OrgHubspotDealStateService.php:20-37`).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "id": "98765",
      "properties": { "dealname": "Riverside Hotel renewal", "amount": "1200.00", "deal_currency_code": "GBP", "dealstage": "closedwon" },
      "checkoutUrlCount": 2
    }
  ]
}
```

**Errors:** `400` with the service's message when its call fails; the admin token errors.

**Side effects:** one call to the service's `GET /deals`, and one query for the counts. Writes nothing.

## GET /v1/admin/sales/deals/{objectId}

Gets one deal with its companies, contacts and line items, and the links and onboarding record made for it: the deal dialog.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.getDealDetails`, when a deal row is opened: `src/app/pages/invoices/invoices.component.ts:67`).

**Request**

| Name       | In   | Type    | Required | Rules                                                                                                                                                                                                          |
| ---------- | ---- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `objectId` | path | integer | yes      | A deal's `object_id` in [`tPri_Org_HubspotDealState`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_hubspotdealstate.md), won or not; otherwise `422` "The selected object id is invalid." |

**Response** `200`: the service's deal details (`deal`, `companies`, `contacts` and `line_items`, passed through), with these fields added (`app/Http/Controllers/v1/Versions/v1_0/Admin/OrgHubspotDealStateController.php:86-108`):

* `checkoutSessionUrls`: the Stripe checkout links logged for the deal, newest first: `companyId`, `parentUuid`, `createdTs` (ms) and `checkoutSessionUrl`.
* `mandateRequestUrls`: the mandate sign-up links logged for the deal, newest first: `companyId`, `parentUuid`, `createdTs` and `mandateRequestUrl`.
* `parentUuid`: the site of the deal's newest GoCardless payment; when that has none, the first site in the two lists above; else `null` (`app/Services/OrgHubspotDealStateService.php:78-101`).
* `orgOnboardingLog`: the deal's first [onboarding log object](#onboarding-log-object), or `null`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "deal": { "properties": { "dealname": "Riverside Hotel renewal", "amount": "1200.00", "deal_currency_code": "GBP", "hs_object_id": "98765" } },
    "companies": [ { "id": "456", "properties": { "name": "Riverside Hotel Ltd", "domain": "example.com" } } ],
    "contacts": [ { "id": "789", "properties": { "firstname": "Jane", "lastname": "Smith", "email": "jane@example.com" } } ],
    "line_items": [ { "id": "555", "properties": { "name": "Snapfix Pro", "amount": "100.00", "recurringbillingfrequency": "monthly", "hs_object_id": "555", "hs_product_id": "42" } } ],
    "checkoutSessionUrls": [ { "companyId": 456, "parentUuid": "123", "createdTs": 1794387595000, "checkoutSessionUrl": "https://checkout.example.com/pay/cs_123" } ],
    "mandateRequestUrls": [],
    "parentUuid": "123",
    "orgOnboardingLog": { "onboardingUuid": "700", "parentUuid": "123", "dealId": 98765, "companyId": 456, "contactId": 789, "onboardingTs": null }
  }
}
```

**Errors:** `422` for a deal that is not in the table, or an ID that is not a whole number ("The object id field must be an integer."); `400` with the service's message when its call fails; the admin token errors.

**Side effects:** one call to the service's `GET /deal/{objectId}`. Reads the link logs, the payment log and the onboarding records; writes nothing.

## GET /v1/admin/sales/gocardless-customer

Gets the GoCardless customer of a company and a contact, with the customer's mandates for one currency: the bank payment status in a deal's companies and contacts.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.getCompanyGocardlessCustomer`, with the deal's currency: `src/app/pages/invoices/components/deal-companies-contacts/deal-companies-contacts.component.ts:190`).

**Request** (query)

| Name                     | In    | Type    | Required | Rules                                                 |
| ------------------------ | ----- | ------- | -------- | ----------------------------------------------------- |
| `companyId`, `contactId` | query | integer | yes      | The HubSpot company and contact IDs                   |
| `currency`               | query | string  | no       | Not checked, and put into the org mapping URL as sent |

**Response** `200`: `data` is a [GoCardless customer object](#gocardless-customer-object). When the mandate lookup fails, the call still succeeds, with only `customerId` set and the other fields at their defaults \[[ASK-209](https://github.com/snapfix/docs/blob/main/ASK.md#ask-209-should-a-failed-mandate-lookup-show-as-no-active-mandate)] (`app/Http/Controllers/v1/Versions/v1_0/Admin/OrgHubspotDealStateController.php:162-193`).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "customerId": "CU000EXAMPLE",
    "activeMandate": true,
    "activeMandateId": "MD000EXAMPLE",
    "createdAt": "2026-01-05T10:00:00Z",
    "allMandates": [ { "id": "MD000EXAMPLE", "status": "active", "createdAt": "2026-01-05T10:00:00Z", "snapfixStatus": "active", "snapfixInstruction": "Ready to take payments" } ]
  }
}
```

**Errors:** `422` for a missing or non-integer `companyId` or `contactId`; `400` with the service's message when the customer lookup fails; the admin token errors.

**Side effects:** two calls to the service: `GET /gocardless/customer/`, then `GET /gocardless/customermandate/`. Writes nothing.

## POST /v1/admin/sales/gocardless-customer-mandate

Creates a GoCardless mandate sign-up link for a customer, and records it: the mandate dialog of a deal's companies and contacts.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.generateMandateUrl`, from the mandate dialog: `src/app/pages/invoices/components/deal-mandate-info-modal/deal-mandate-info-modal.component.ts:70`). The app sends the deal's site, or `null`.

**Request** (JSON or form)

| Name                  | In   | Type    | Required | Rules                                                                                                                                             |
| --------------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customerId`          | body | string  | yes      | The GoCardless customer ID                                                                                                                        |
| `currency`            | body | string  | yes      | The currency code                                                                                                                                 |
| `dealId`, `companyId` | body | integer | yes      | The HubSpot deal and company IDs                                                                                                                  |
| `parentUuid`          | body | string  | no       | Nullable. The site, stored with the link. Send it, even as `null`: without the key, the call fails with `500` after the link is made (`:218-224`) |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "mandateUrl": "https://pay.example.com/mandate/123" }
}
```

**Errors:** `422` with the first failed rule's message; `400` with the service's message when its call fails; the admin token errors.

**Side effects:** calls the service's `POST /gocardless/customermandate/` with the customer and the currency. Inserts a [`tPri_Org_GoCardlessMandateUrlLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_gocardlessmandateurllog.md) row with the site, deal, company, customer and link, which the deal details list in `mandateRequestUrls` (`app/Http/Controllers/v1/Versions/v1_0/Admin/OrgHubspotDealStateController.php:201-229`).

## POST /v1/admin/sales/gocardless-payments

Lists the GoCardless payments made for some line items: the payments of the deal dialog.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.getGocardlessPayments`, with the deal's line item IDs: `src/app/pages/invoices/components/deal-modal/deal-modal.component.ts:342`).

**Request** (JSON or form)

| Name          | In   | Type              | Required | Rules                                              |
| ------------- | ---- | ----------------- | -------- | -------------------------------------------------- |
| `lineItemIds` | body | array of integers | yes      | The HubSpot line item IDs; each must be an integer |

**Response** `200`: `data` is the service's list of [GoCardless payments](#gocardless-payment-object), passed through.

**Errors:** `422` for a missing list or an ID that is not an integer; `400` with the service's message when its call fails; the admin token errors.

**Side effects:** one call to the service's `GET /gocardless/payments/`, with one `hubspot_line_item_ids` query value per ID. Writes nothing.

## POST /v1/admin/sales/onboarding

Creates the onboarding record that links a deal, its company and its contact to a site. The record's UUID makes the setup link that the deal dialog shows, `<onboarding app>/<onboardingUuid>`, which opens the [setup form](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md) \[[ASK-41](https://github.com/snapfix/docs/blob/main/ASK.md#ask-41-which-setup-link-can-the-live-pass-open)].

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.createOnboarding`, from the deal dialog: `src/app/pages/invoices/components/deal-modal/deal-modal.component.ts:379`). The app sends the deal's `parentUuid`, and offers "Create" only while the deal has no record.

**Request** (JSON or form)

| Name                               | In   | Type    | Required | Rules                                                                                                                |
| ---------------------------------- | ---- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`                       | body | string  | yes      | The site. Saved as `uuid_tParent`; not checked against the sites                                                     |
| `dealId`, `companyId`, `contactId` | body | integer | yes      | The HubSpot deal, company and contact IDs. Saved as `hubspot_deal_id`, `hubspot_company_id` and `hubspot_contact_id` |

**Response** `200`: `data` is the new [onboarding log object](#onboarding-log-object). The message is the bare key `messages.org_created` (`app/Http/Controllers/v1/Versions/v1_0/Admin/OrgOnboardingLogController.php:18-24`).

```json
{
  "status": "success",
  "message": "messages.org_created",
  "data": { "onboardingUuid": "700", "parentUuid": "123", "dealId": 98765, "companyId": 456, "contactId": 789, "onboardingTs": null }
}
```

**Errors:** `422` for a missing field or an ID that is not an integer; the admin token errors.

**Side effects:** inserts a [`tPri_Org_OnboardingLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_onboardinglog.md) row, with the staff user as creator. Each call adds a row, even when the deal has one; the deal details show the first. The admin app offers Create only while the deal has none (webadmin\_angular @ db972390b8, `src/app/pages/invoices/components/deal-modal/deal-modal.component.html:68-81`).

## GET /v1/admin/sales/stripe-customer

Gets the Stripe customer of a company and a contact: the card payment status in a deal's companies and contacts.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`InvoiceService.getCompanyStripeCustomer`: `src/app/pages/invoices/components/deal-companies-contacts/deal-companies-contacts.component.ts:174`). The app reads `id` and `active_cardpayment`.

**Request** (query)

| Name                     | In    | Type    | Required | Rules                               |
| ------------------------ | ----- | ------- | -------- | ----------------------------------- |
| `companyId`, `contactId` | query | integer | yes      | The HubSpot company and contact IDs |

**Response** `200`: `data` is the customer that the service returns, passed through.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "id": "cus_123", "active_cardpayment": true }
}
```

**Errors:** `422` "The company id field is required." or "The company id field must be an integer." (the same for `contactId`); `400` with the service's message when its call fails; the admin token errors.

**Side effects:** one call to the service's `GET /stripe/customer/`. Writes nothing.

## GET /v1/admin/survey

Lists the pre-registration surveys, active and inactive: the [Surveys](https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.md) page.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`SurveyService.getSurveyList`: `src/app/pages/survey/survey.component.ts:164`). The app sends no `limit`, so every survey comes back.

**Request**

| Name     | In    | Type    | Required | Rules                                                                              |
| -------- | ----- | ------- | -------- | ---------------------------------------------------------------------------------- |
| `limit`  | query | integer | no       | Page size, not checked. With it, the list is paged and the answer has `pagination` |
| `offset` | query | integer | no       | Page number, from 1; default `1`. Read only with `limit`                           |

**Response** `200`: `data.items` is the list of live [survey objects](#survey-object), in database order. With `limit`, `data.pagination` holds `total`, `perPage`, `currentPage`, `lastPage`, `from` and `to` (`app/Http/Resources/v1/Admin/PreRegSurveyCollection.php`).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "items": [
      {
        "uuid": "400",
        "dynamicFormJson": { "page_form": { "title": "Before you start", "submit_button_text": "Send", "description": "", "components": [] } },
        "startTs": 1794355200000,
        "endTs": 1797033599000,
        "ipFilterJson": { "city": [], "continent": [], "region": [], "countryCode": ["GB"] },
        "deviceType": ["android", "ios"],
        "inActive": 0,
        "createdTs": "2026-11-14T08:35:00Z",
        "modifiedTs": "2026-11-14T08:35:00Z",
        "createdByUserUuid": "200",
        "modifiedByUserUuid": "200"
      }
    ]
  }
}
```

**Errors:** the admin token errors.

**Side effects:** none.

## POST /v1/admin/survey

Creates a pre-registration survey: its form, its dates, and the countries and devices that see it. The apps read the active survey from [GET /v1/guest/survey/prereg](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-v1guestsurveyprereg).

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`SurveyService.saveQrForm`, from the survey dialog when the survey is new: `src/app/pages/survey/components/survey-modal/survey-modal.component.ts:56`). The app sends the start as midnight GMT and the end as 23:59:59 GMT of the picked days, and `ipFilterJson` with `city`, `continent`, `region` and `countryCode` (`src/app/services/survey/survey.service.ts:30-75`).

**Request** (JSON or form)

| Name              | In   | Type    | Required       | Rules                                                                                                                                            |
| ----------------- | ---- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dynamicFormJson` | body | object  | yes            | The form: `page_form` with `title`, `submit_button_text`, `description` and `components`. Its shape is not checked. Saved as `dynamic_form_json` |
| `startTs`         | body | integer | yes            | Start, in ms                                                                                                                                     |
| `endTs`           | body | integer | with `startTs` | End, in ms. Not checked to come after `startTs`                                                                                                  |
| `inActive`        | body | integer | yes            | `0` (active) or `1`. Saved as `fInActive`                                                                                                        |
| `ipFilterJson`    | body | object  | no             | Saved as `ip_filter_json`. `countryCode` is a list of two-letter codes; an empty list means every country                                        |
| `deviceType`      | body | array   | no             | Any of `android`, `ios` and `web`; an empty list means every device. Saved as `device_type`                                                      |

A missing or `null` `startTs` or `endTs` fails with `500` "An unexpected error occurred. Please try again later.", because the overlap rule is built from both values before validation runs (`app/Http/Requests/v1/Admin/User/CreateOrUpdateUserSurveyRequest.php:23`, `app/Rules/UniqueDateRangeRule.php:19-26`).

The dates may not overlap those of a live, active survey, that is one that starts before the new end and ends after the new start (`app/Rules/UniqueDateRangeRule.php:28-57`):

* With countries, a clash is an overlapping survey that lists any of the same countries: "One or more country codes are already present in the database."
* Without countries, a clash is an overlapping survey whose country list is empty: "The date range overlaps with an existing record."
* Device types are not compared \[[ASK-207](https://github.com/snapfix/docs/blob/main/ASK.md#ask-207-which-surveys-should-the-date-overlap-check-compare)], and the check runs even when the new survey is inactive \[[ASK-207](https://github.com/snapfix/docs/blob/main/ASK.md#ask-207-which-surveys-should-the-date-overlap-check-compare)].

**Response** `200`: `data` is the new [survey object](#survey-object). The message is "Pre Reg Survey created successfully".

**Errors:** `422` with the first failed rule's message, the clash messages included; `500` as above; the admin token errors.

**Side effects:** inserts a [`tPri_PreRegSurvey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_preregsurvey.md) row, with the staff user as creator.

## PUT /v1/admin/survey/{uuid}

Changes a pre-registration survey. The rules are those of [POST /v1/admin/survey](#post-v1adminsurvey), and the survey itself is left out of the overlap check.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`SurveyService.saveQrForm`, from the survey dialog when the survey exists: `src/app/pages/survey/components/survey-modal/survey-modal.component.ts:56`, `src/app/services/survey/survey.service.ts:69-72`).

**Request:** path `uuid`, then the body of [POST /v1/admin/survey](#post-v1adminsurvey).

**Response** `200`: the [survey object](#survey-object) after the change. The message is "Pre Reg Survey updated successfully".

**Errors:** `422` with the first failed rule's message; `500` for a missing or `null` `startTs` or `endTs`, as for the create route; `404` "Resource not found" for an unknown or deleted survey, checked after the body; the admin token errors.

**Side effects:** updates the [`tPri_PreRegSurvey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_preregsurvey.md) row, with the staff user as modifier.

## DELETE /v1/admin/survey/{uuid}

Deletes a pre-registration survey: the delete button of the Surveys page.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`SurveyService.deleteSurveyItem`: `src/app/pages/survey/survey.component.ts:179`).

**Request**

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

**Response** `200`: `data` is `null`. The message is "Pre Reg Survey deleted successfully".

**Errors:** `404` "Resource not found" for an unknown or deleted survey; the admin token errors.

**Side effects:** soft-deletes the [`tPri_PreRegSurvey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_preregsurvey.md) row: `fDeleted` 1.

## POST /v1/admin/user-relations/multiple

Adds users to several groups in one request, and creates the users that don't exist yet: the "Upload User(s) To Multiple Groups" dialog of the [Group users](https://docs.snapfix.com/how-the-apps-work/screens/staff/group-users.md) page.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`GroupUsersService.uploadUsersToMultipleGroups`: `src/app/pages/group-users/components/upload-multiple-groups-users-modal/upload-multiple-groups-users-modal.component.ts:150`). The app sends every row's `countryCode` and `mobile` as numbers, `0` when they are empty (`src/app/services/group-users/group-users.service.ts:127-158`).

**Request** (JSON)

| Name                                                              | In   | Type    | Required                                                 | Rules                                                                                                                                                                                                   |
| ----------------------------------------------------------------- | ---- | ------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `businesses`                                                      | body | array   | yes                                                      | One item per group                                                                                                                                                                                      |
| `businesses.*.uuid`                                               | body | string  | yes                                                      | A live group or asset register. An unknown or deleted one is skipped without an error                                                                                                                   |
| `businesses.*.users`                                              | body | array   | yes                                                      | One item per user. No maximum                                                                                                                                                                           |
| `businesses.*.users.*.username`                                   | body | string  | unless `countryCode` is sent                             | The sign-in email                                                                                                                                                                                       |
| `businesses.*.users.*.countryCode`, `businesses.*.users.*.mobile` | body | integer | each with the other, and both when `username` is missing | The mobile number. A `0` in either drops both. Every row must carry both keys: a row without them fails with `500` (`app/Http/Requests/v1/Admin/BusinessUser/CreateMultipleUserBusinessRequest.php:44`) |
| `businesses.*.users.*.password`                                   | body | string  | yes                                                      | Hashed and stored for a new user only; an existing user keeps their password. No strength rule                                                                                                          |
| `businesses.*.users.*.firstname`, `businesses.*.users.*.lastname` | body | string  | yes                                                      | The names                                                                                                                                                                                               |
| `businesses.*.users.*.address`                                    | body | string  | no                                                       | The address                                                                                                                                                                                             |
| `businesses.*.users.*.userRole`                                   | body | string  | yes                                                      | `Admin` or `User`                                                                                                                                                                                       |

A row's user is found by mobile number (country code and number), then by username, which wins when both match. When the two match different users, the row fails with "User duplication found!". A user who is found is added as they are (`app/Services/UserService.php:334-394`).

**Response** `200`: `data` is a list of [user relation result objects](#user-relation-result-object), one per group that exists. The message is "Users added to the business successfully".

```json
{
  "status": "success",
  "message": "Users added to the business successfully",
  "data": [
    {
      "businessUuid": "400",
      "success": { "count": 2 },
      "failures": {
        "count": 1,
        "users": [
          {
            "message": "User exists and is already part of the business",
            "user": { "fFirstName": "Jane", "fLastName": "Smith", "fUsername": "jane@example.com", "fCountryCode": 44, "fMobile": "7700900123", "fAddress": null, "uuid_tUserType": "role-100", "uuid_tBusiness": "400" }
          }
        ]
      }
    }
  ]
}
```

**Errors:** `422` with the first failed rule's message, for example "The businesses.0.users.0.password field is required."; `400` "No businesses found!" when none of the groups exists; `500` for a database or PHP error part way through, which keeps the rows written so far; the admin token errors. A row that cannot be added is a failure in the answer, not an error.

**Side effects** (`app/Http/Controllers/v1/Versions/v1_0/Admin/UserAssetBusinessController.php:166-216`):

* Inserts a [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row for each new user, with the text `admin` as creator and modifier \[[ASK-77](https://github.com/snapfix/docs/blob/main/ASK.md#ask-77-who-should-be-recorded-as-the-creator-of-groups-users-and-sites-made-through-the-staff-admin-routes)], and a hash row in [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) (`app/Services/UserService.php:415-443`).
* Inserts a [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row for each user who has no membership of the group yet, with the role and the active onboard state, and the staff user as creator. A user with a live or a removed membership is listed as a failure and left as is (`app/Services/UserAssetBusinessService.php:90-119`).
* When a new member has a deleted site row on the group's site, restores it with the user type `user`, not `normal` (`app/Services/UserAssetBusinessService.php:66-79`).
* Queues a Firebase Realtime Database write of the site's user count, for the first group's site only.
* The body, passwords included, goes into the request log. A "User duplication found!" failure repeats the row as sent, password included.
* Each row costs several queries and a password hash, in one request with no transaction.

## PUT /v1/admin/user-relations/multiple

Changes the permissions of several members of one group: the permissions dialog of the [Group users](https://docs.snapfix.com/how-the-apps-work/screens/staff/group-users.md) page.

* **Auth:** admin token.
* **Used by:** webadmin\_angular (`GroupUsersService.updateUsersPermissions`: `src/app/pages/group-users/components/group-users-permissions-modal/group-users-permissions-modal.component.ts:142`). The app sends `1` or `0` for each permission it shows (`src/app/services/group-users/group-users.service.ts:160-180`).

**Request** (JSON)

| Name                             | In   | Type    | Required | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `businessUuid`                   | body | string  | yes      | The group. Not checked to exist                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `userPermissions`                | body | array   | yes      | One item per member                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `userPermissions.*.userUuid`     | body | string  | yes      | The member. A user with no live membership of the group is skipped without an error                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `userPermissions.*.<permission>` | body | boolean | no       | One key per permission: `perJobViewAll`, `perJobCreateNew`, `perJobDelete`, `perJobArchive`, `perJobHideNotes`, `perJobMoveToRed`, `perJobMoveToAmber`, `perJobMoveToGreen`, `perJobReportGenerate`, `perJobCreatePlanned`, `perJobToDoCreate`, `perJobToDoEdit`, `perJobToDoDelete`, `perAssignUser`, `perBusSettingsScreenAccess`, `perBusCreateNew`, `perBusSettingsEditUser`, `perBusSettingsEditTagHeading`, `perBusSettingsEditTag`, `perAccessDocuments`, `perAcceptAssign` (`app/Enums/Permission.php`). The member's role is kept |

**Response** `200`: `data` is `null`. The message is "Users relation updated successfully".

**Errors:** `422` with the first failed rule's message; the admin token errors.

**Side effects:** updates the permissions sent, `fModifiedTs` and the staff user as modifier on each matched [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row, one update per member (`app/Http/Controllers/v1/Versions/v1_0/Admin/UserAssetBusinessController.php:248-270`).

## GET /cs-dashboard

Returns the customer support dashboard: one record per paying site, with its risk score, invoice and renewal dates, user, group and activity counts, and its admins.

* **Auth:** user token (authpy JWT in `Authorization: Bearer`). Nothing checks the staff flag, so any signed-in user gets every record, the admins' contact details included.
* **Used by:** webadmin\_angular (`CsDashboardService.getCSDashboardData`, when the [CS dashboard](https://docs.snapfix.com/how-the-apps-work/screens/staff/cs-dashboard.md) page opens: `src/app/pages/cs-dashboard/cs-dashboard.component.ts:119`).

**Request:** none.

**Response** `200`: `data` is a list of site records: the live sites whose customer type starts with `paying_`, highest risk score first (apipy @ 0e83c85e5a, `model/v4/t_parent.py:678-711`). The answer comes from a copy saved on the server, rebuilt when it is more than 12 hours old (`:663-676`).

| Field                                                                                                 | Type                    | Meaning                                                                                                                             |
| ----------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `account_name`                                                                                | string                  | The site's ID and name                                                                                                              |
| `fAddress`, `fCreatedTs`, `fFirstInvoiceDateTs`, `fNextRenewalDateTs`, `fRiskScoreTs`                 | string, integer or null | The site's fields as stored; times in ms                                                                                            |
| `fRiskScore`, `fRiskScore_unit`                                                                       | integer, string         | The stored risk score divided by 100 and rounded down, a percentage; the unit is always `%`                                         |
| `users`                                                                                               | integer                 | The site's group membership rows, deleted ones included                                                                             |
| `active_users`, `active_unique_users`                                                                 | integer                 | Live memberships of live users in live groups, and the distinct users among them                                                    |
| `groups`, `active_groups`                                                                             | integer                 | The site's group and asset register rows, deleted ones included, and the live ones                                                  |
| `super_admin`                                                                                         | array                   | The site's live admins: `uuid`, `fUsername` (an email address), `fCountryCode`, `fMobile`, `fFirstName`, `fLastName` and `fImage`   |
| `activity`, `manual_task`, `nfc`, `scheduled_task`, `tag`, `timecost`, `checklist`, `followandassign` | integer                 | Sums of the site's monthly task chat metrics of each kind, for January 2019 to December 2023 only (`model/v4/t_parent.py:822-1164`) |
| `schedules`, `web_reports`                                                                            | integer                 | Always `0`: nothing fills them                                                                                                      |

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [
    {
      "uuid": "123",
      "account_name": "Riverside Hotel",
      "fAddress": "1 Quay Street",
      "fCreatedTs": 1764000000000,
      "fFirstInvoiceDateTs": 1764000000000,
      "fNextRenewalDateTs": 1796000000000,
      "fRiskScore": 40,
      "fRiskScore_unit": "%",
      "fRiskScoreTs": 1794300000000,
      "users": 14,
      "active_users": 12,
      "active_unique_users": 9,
      "groups": 4,
      "active_groups": 3,
      "super_admin": [ { "uuid": "200", "fUsername": "jane@example.com", "fCountryCode": 44, "fMobile": "7700900123", "fFirstName": "Jane", "fLastName": "Smith", "fImage": null } ],
      "activity": 120,
      "manual_task": 30,
      "nfc": 4,
      "scheduled_task": 12,
      "schedules": 0,
      "tag": 9,
      "timecost": 0,
      "checklist": 6,
      "followandassign": 3,
      "web_reports": 0
    }
  ]
}
```

**Errors:** `200` with `result` `false` and the parser's message when the saved copy cannot be read as JSON; `401` "Access token expired"; `500` without a JSON body for anything else, such as a missing copy or a database error: the route catches only `ValueError` (`app.py:3810-3829`).

**Side effects:** when the saved copy is more than 12 hours old, the route rebuilds the records and rewrites the copy on the server, `/home/ubuntu/pyapp/model/v4/dashboard_data_v2.json` (`model/v4/t_parent.py:1166-1176`). A copy of that file, with the admins' contact details, is tracked in the apipy repository. Each call also writes an abuse-check log row.

## GET /email-logs

Lists the email delivery log, one row per delivery event, with paging, search, filters and sorting: the email table of the [SMS/E-mail delivery](https://docs.snapfix.com/how-the-apps-work/screens/staff/sms-email-delivery.md) page.

* **Auth:** user token. Nothing checks the staff flag, so any signed-in user can read every email's recipients and subject. The search and filter values go into the SQL text inside quotes, and `offset` as sent.
* **Used by:** webadmin\_angular (`SmsEmailDeliveryService.getDeliveryLogs` with the email type, from the delivery table: `src/app/pages/sms-email-delivery/components/delivery-table/delivery-table.component.ts:51`). The table sends `offset` as page size times the pages before, `limit`, the sort, and one `filter_*` value per column search (`src/app/services/sms-email-delivery/sms-email-delivery.service.ts:22-49`).

**Request** (query)

| Name                                                                                                   | In    | Type    | Required | Rules                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------ | ----- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offset`                                                                                               | query | integer | no       | Default `0`                                                                                                                                                                |
| `limit`                                                                                                | query | integer | no       | Default `10`; `0` or less also gives `10`; a value that is not a number answers `result` `false`. No maximum                                                               |
| `search`                                                                                               | query | string  | no       | Contains-match on the recipient, subject, sender, status detail and message ID                                                                                             |
| `status`                                                                                               | query | string  | no       | Exact match on the event type                                                                                                                                              |
| `date_from`, `date_to`                                                                                 | query | string  | no       | Lower and upper bound on `sent_at`, both inclusive                                                                                                                         |
| `filter_recipient`, `filter_subject`, `filter_from_email`, `filter_status_detail`, `filter_message_id` | query | string  | no       | One contains-match each                                                                                                                                                    |
| `sort_field`                                                                                           | query | string  | no       | `sent_at` (default), `delivered_at`, `recipient`, `subject`, `from_email`, `event_type`, `status_detail`, `message_id` or `fCreatedts`; any other value sorts by `sent_at` |
| `sort_type`                                                                                            | query | string  | no       | `-1` or missing sorts descending; any other value ascending                                                                                                                |

Events of type `Send` and rows without a send time are left out (apipy @ 0e83c85e5a, `model/t_communication_logs.py:29-163`).

**Response** `200`: `data` is a list of [`tbl_email_logs`](https://docs.snapfix.com/engineering-reference/db/tables/tbl_email_logs.md) rows, and `total` the number of matching rows. `total` is counted on the first page only (`offset` `0`); later pages answer `0`.

| Field                                                                                    | Type            | Meaning                                                             |
| ---------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------- |
| `uuid`                                                                                   | string          | The row's ID                                                        |
| `sent_at`, `delivered_at`                                                                | string or null  | Times in UTC, as HTTP dates such as `Fri, 13 Nov 2026 09:12:00 GMT` |
| `recipient`, `all_recipients`                                                            | string          | The email addresses the message went to                             |
| `subject`, `from_email`, `from_domain`, `sender_identity`, `sent_by_iam`, `operation`    | string or null  | The message and how it was sent                                     |
| `message_id`, `event_type`, `status_detail`, `recipient_isp`, `source_ip`, `outgoing_ip` | string or null  | The provider's details of the event                                 |
| `processing_time_ms`                                                                     | integer or null | The provider's processing time                                      |
| `fCreatedts`                                                                             | integer         | When the row was written, in ms                                     |

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [
    { "uuid": "e-1", "sent_at": "Fri, 13 Nov 2026 09:12:00 GMT", "delivered_at": "Fri, 13 Nov 2026 09:12:04 GMT", "recipient": "jane@example.com", "subject": "Task reminder", "from_email": "noreply@example.com", "event_type": "Delivery", "status_detail": "delivered", "message_id": "m-123", "fCreatedts": 1794387100000 }
  ],
  "total": 1
}
```

**Errors:** `200` with `result` `false` and the error text when reading fails, a database error included; `401` "Access token expired".

**Side effects:** none, apart from the abuse-check log row.

## GET /sms-logs

Lists the SMS delivery log, with paging, search, filters and sorting: the SMS table of the [SMS/E-mail delivery](https://docs.snapfix.com/how-the-apps-work/screens/staff/sms-email-delivery.md) page.

* **Auth:** user token. Nothing checks the staff flag, so any signed-in user can read every message's phone number. Values go into the SQL text as for [GET /email-logs](#get-email-logs).
* **Used by:** webadmin\_angular (`SmsEmailDeliveryService.getDeliveryLogs` with the SMS type: `src/app/pages/sms-email-delivery/components/delivery-table/delivery-table.component.ts:51`).

**Request** (query)

| Name                                                                             | In    | Type    | Required | Rules                                                                                                                                                           |
| -------------------------------------------------------------------------------- | ----- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offset`, `limit`                                                                | query | integer | no       | As for [GET /email-logs](#get-email-logs)                                                                                                                       |
| `search`                                                                         | query | string  | no       | Contains-match on the recipient phone, status, source and message ID                                                                                            |
| `status`                                                                         | query | string  | no       | Exact match on the status                                                                                                                                       |
| `date_from`, `date_to`                                                           | query | string  | no       | Lower and upper bound on `sent_at`, both inclusive                                                                                                              |
| `filter_recipient_phone`, `filter_message_id`, `filter_source`, `filter_carrier` | query | string  | no       | One contains-match each                                                                                                                                         |
| `sort_field`                                                                     | query | string  | no       | `sent_at` (default), `recipient_phone`, `status`, `sms_type`, `carrier`, `cost_usd`, `source`, `message_id` or `fCreatedts`; any other value sorts by `sent_at` |
| `sort_type`                                                                      | query | string  | no       | As for [GET /email-logs](#get-email-logs)                                                                                                                       |

Rows without a send time are left out (`model/t_communication_logs.py:220-338`).

**Response** `200`: `data` is a list of [`tbl_sms_logs`](https://docs.snapfix.com/engineering-reference/db/tables/tbl_sms_logs.md) rows, and `total` as for [GET /email-logs](#get-email-logs).

| Field                                                                        | Type            | Meaning                                            |
| ---------------------------------------------------------------------------- | --------------- | -------------------------------------------------- |
| `uuid`                                                                       | string          | The row's ID                                       |
| `sent_at`                                                                    | string or null  | The send time in UTC, as an HTTP date              |
| `recipient_phone`                                                            | string          | The number the message went to                     |
| `message_id`, `status`, `sms_type`, `carrier`, `provider_response`, `source` | string or null  | The provider's details                             |
| `cost_usd`                                                                   | string or null  | The price, as a decimal string such as `"0.00750"` |
| `message_parts`                                                              | integer or null | The number of parts                                |
| `fCreatedts`                                                                 | integer         | When the row was written, in ms                    |

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [ { "uuid": "s-1", "sent_at": "Fri, 13 Nov 2026 09:12:00 GMT", "recipient_phone": "+447700900123", "message_id": "sm-123", "status": "delivered", "sms_type": "Transactional", "carrier": "Example Mobile", "cost_usd": "0.00750", "message_parts": 1, "provider_response": "OK", "source": "SnapfixAlerts", "fCreatedts": 1794387100000 } ],
  "total": 1
}
```

**Errors:** as for [GET /email-logs](#get-email-logs).

**Side effects:** none, apart from the abuse-check log row.

## GET /support-hours/{parent\_uuid}

Gets a site's support hours: the site's details, its minutes balance and its entries. The [Support logs](https://docs.snapfix.com/how-the-apps-work/screens/staff/support-logs.md) page reads it.

* **Auth:** user token. Nothing checks the staff flag, so any signed-in user can read any site's entries and its staff notes.
* **Used by:** webadmin\_angular (`SupportService.getSupportLogs`: `src/app/pages/support-logs/support-logs.component.ts:48`).

**Request**

| Name          | In   | Type   | Required | Rules       |
| ------------- | ---- | ------ | -------- | ----------- |
| `parent_uuid` | path | string | yes      | A live site |

The route also reads `search`, `sort_field` and `sort_type` from the query, but nothing uses them.

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

**Errors:** `200` with `result` `false`: "invalid parent" (an unknown or deleted site); "no support account logs found!" (the site has no live entry, so no detail comes back either) (apipy @ 0e83c85e5a, `model/t_parent_support.py:100-145`).

**Side effects:** none, apart from the abuse-check log row.

## POST /support-hours/{parent\_uuid}

Adds an entry to a site's support hours: a note, a deposit, a withdrawal or a credit of minutes.

* **Auth:** user token. The creator is the token's user, not a body field (`app.py:3424-3448`). Nothing checks the staff flag.
* **Used by:** webadmin\_angular (`SupportService.saveSupportLog`, from the add-entry dialog: `src/app/pages/support-logs/components/support-logs-modal/support-logs-modal.component.ts:37`). The app sends `type`, `description` and `minutes` (`src/app/services/support/support.service.ts:27-36`).

**Request** (JSON body)

| Name          | In   | Type    | Required             | Rules                                                                                                                                                                                                   |
| ------------- | ---- | ------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuid` | path | string  | yes                  | A live site                                                                                                                                                                                             |
| `type`        | body | integer | yes                  | `0` note, `1` deposit, `2` withdrawal, `3` credit; another number gives "invalid type". The admin app labels `0` "Delete (remove hours added by accident)", but its minutes do not count in the balance |
| `description` | body | string  | for type `0`         | The note's text. Stored for the other types too when sent                                                                                                                                               |
| `minutes`     | body | integer | for types `1` to `3` | Must not be `0`: "invalid params". Negative values are accepted                                                                                                                                         |

An empty body, or a form body, answers "invalid params"; a body that is not JSON answers with the parser's message.

**Response** `200`: `data` is the site's [support hours object](#support-hours-object) after the insert.

**Errors:** `200` with `result` `false`: "invalid params"; "invalid type"; "invalid parent" (`model/t_parent_support.py:218-270`).

**Side effects:** inserts a [`tPri_ParentSupportAccount`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentsupportaccount.md) row, not approved, with the type, description, minutes, the time and the token's user as creator. A credit (type `3`) marks every other credit row of the site deleted, with the token's user as deleter, so the site keeps one credit (`:286-287`). Each call also writes an abuse-check log row.

## PUT /support-hours/{parent\_uuid}

Approves or unapproves support-hours entries of a site: the approve button of the Support logs page.

* **Auth:** user token. The approver is the token's user. Nothing checks the staff flag, and nothing stops the creator of an entry from approving it \[[ASK-203](https://github.com/snapfix/docs/blob/main/ASK.md#ask-203-what-should-approving-support-minutes-mean-and-who-may-approve-or-delete-entries)].
* **Used by:** webadmin\_angular (`SupportService.approveSupportLog`, with `approved` `1` and one entry: `src/app/pages/support-logs/support-logs.component.ts:64`).

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                                                                                                                                                                    |
| ------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parent_uuid` | path | string           | yes      | A live site                                                                                                                                                              |
| `approved`    | body | integer          | yes      | `1` approves, `0` unapproves; another value gives "invalid params"                                                                                                       |
| `log_uuids`   | body | array of strings | yes      | The entries; an empty list gives "invalid params". Each must be a live entry of any site: when none is, "invalid logs"; when only some are, "invalid log data to modify" |

The entries are not checked to belong to the path's site: the update then changes only those that do, and the call still succeeds (`model/t_parent_support.py:291-352`).

**Response** `200`: `data` is the site's [support hours object](#support-hours-object) after the change.

**Errors:** `200` with `result` `false`: "invalid params"; "invalid parent"; "invalid logs"; "invalid log data to modify".

**Side effects:** sets `fApproved`, `fApprovedTs`, `uuid_tUser_ApprovedBy` (the token's user) and `fServerTs` on the listed rows of the path's site in [`tPri_ParentSupportAccount`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentsupportaccount.md), for an unapproval too. Each call also writes an abuse-check log row.

## DELETE /support-hours/{parent\_uuid}/{log\_uuid}

Deletes one support-hours entry: the delete button of the Support logs page. Approved entries can be deleted too \[[ASK-203](https://github.com/snapfix/docs/blob/main/ASK.md#ask-203-what-should-approving-support-minutes-mean-and-who-may-approve-or-delete-entries)].

* **Auth:** user token. The deleter is the token's user. Nothing checks the staff flag.
* **Used by:** webadmin\_angular (`SupportService.deleteSupportLog`: `src/app/pages/support-logs/support-logs.component.ts:78`).

**Request**

| Name          | In   | Type   | Required | Rules                                                                                                                         |
| ------------- | ---- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuid` | path | string | yes      | A live site                                                                                                                   |
| `log_uuid`    | path | string | yes      | A live entry, of any site: otherwise "invalid log". For an entry of another site, nothing changes and the call still succeeds |

**Response** `200`: `data` is the site's [support hours object](#support-hours-object) after the delete.

**Errors:** `200` with `result` `false`: "invalid parent"; "invalid log" (`model/t_parent_support.py:358-397`).

**Side effects:** soft-deletes the entry of the path's site in [`tPri_ParentSupportAccount`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentsupportaccount.md): `fDeleted` 1, `fDeletedTs` and `uuid_tUser_DeletedBy`, the token's user. Each call also writes an abuse-check log row.

## GET /v4/parents

Lists sites with their user, group and task counts, their HubSpot and Xero links, and the warning counts, with paging, search and filters: the account lists of the admin app.

* **Auth:** user token. Nothing checks the staff flag, so any signed-in user can list every site with its email key. `offset`, `limit` and `sort_field` go into the SQL text as sent.
* **Used by:** webadmin\_angular (`AccountService.getAccounts`, from the [Accounts](https://docs.snapfix.com/how-the-apps-work/screens/staff/accounts.md) page, `src/app/pages/account/account.component.ts:66`, the account picker, `src/app/components/accounts-select/accounts-select.component.ts:118`, and the accounts column of the mapping page, `src/app/pages/org-mapping/org-mapping-accounts/org-mapping-accounts.component.ts:134`). The app sends `offset`, `limit`, `search`, `warning_filter`, `type`, and `sort_field` `fName` with a sort (`src/app/services/account/account.service.ts:39-64`).

**Request** (query)

| Name             | In    | Type    | Required | Rules                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------- | ----- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offset`         | query | integer | no       | Row offset; default `0`                                                                                                                                                                                                                                                                                                                                                                                       |
| `limit`          | query | integer | no       | Page size; default `50`. No maximum                                                                                                                                                                                                                                                                                                                                                                           |
| `search`         | query | string  | no       | Contains-match on the site name, ignoring case                                                                                                                                                                                                                                                                                                                                                                |
| `type`           | query | string  | no       | Exact match on the customer type                                                                                                                                                                                                                                                                                                                                                                              |
| `sort_field`     | query | string  | no       | A column name; default `id`. Not checked against a list                                                                                                                                                                                                                                                                                                                                                       |
| `sort_type`      | query | string  | no       | `-1` sorts descending; anything else ascending (the default)                                                                                                                                                                                                                                                                                                                                                  |
| `warning_filter` | query | string  | no       | `email_key`, `first_invoice_date`, `renewal_date`, `email_user_admin_uuid`, `parent_admin` or `past_renewal_date`; another value gives "invalid warning filter". Keeps the live paying sites with that gap: no email key, no first invoice date, no renewal date, no email admin, no live site admin, or a renewal date in the past. When no site has the gap, the filter is dropped and every site is listed |

Without `type`, every customer type is listed, and deleted sites too, with their `fDeleted` (apipy @ 0e83c85e5a, `model/v4/t_parent.py:22-252`).

**Response** `200`: `data` is `{ "total_count": N, "items": [...] }`, and `warnings` too when `offset` is `0` and no `warning_filter` is sent: the number of live paying sites with each gap (`:331-441`).

| Item field                                                                                                                   | Type            | Meaning                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------- |
| `id`, `uuid`, `uuid_tOrg`                                                                                                    | integer, string | The row ID, the site's ID and its organization                                                 |
| `fName`, `fImage`, `fAddress`, `origin`, `email_key`, `timezone_name`                                                        | string or null  | The site's fields; `fName` trimmed                                                             |
| `fCustomerType`, `fCustomerTypeTs`                                                                                           | string, integer | The customer type and when it was set, in ms                                                   |
| `fFirstInvoiceDateTs`, `fNextRenewalDateTs`, `fRiskScore`, `fRiskScoreTs`                                                    | integer or null | Invoice, renewal and risk values as stored                                                     |
| `fDeleted`, `fCreatedTs`, `fModifiedTs`                                                                                      | integer         | Row state and times, in ms                                                                     |
| `user_count`                                                                                                                 | integer         | Distinct live users with a live site row or a live membership in one of the site's live groups |
| `group_count`, `job_count`                                                                                                   | integer         | The site's live groups and asset registers, and their live tasks                               |
| `hubspot_company_parent_item`, `hubspot_contact_parent_item`, `xero_contacts_parent_item`, `xero_sales_invoices_parent_item` | array           | The live links of the site, each `{ "uuid", "name" }`                                          |

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "total_count": 1,
    "items": [
      { "id": 42, "uuid": "123", "uuid_tOrg": null, "fName": "Riverside Hotel", "fCustomerType": "paying_customer", "fAddress": "1 Quay Street", "origin": "web", "email_key": "riverside", "fDeleted": 0, "user_count": 12, "group_count": 3, "job_count": 140, "hubspot_company_parent_item": [ { "uuid": "800", "name": "Riverside Hotel Ltd" } ], "hubspot_contact_parent_item": [], "xero_contacts_parent_item": [], "xero_sales_invoices_parent_item": [] }
    ],
    "warnings": { "without_parent_admin": 4, "without_first_invoice_date": 10, "without_renewal_date": 7, "without_email_key": 3, "without_email_user_admin_uuid": 2, "past_renewal_date": 1 }
  }
}
```

**Errors:** `200` with `result` `false`: "record(s) not found" when no site matches; "invalid warning filter". A database error, such as one from a bad `sort_field`, answers `500` without a JSON body (`app.py:2819-2838`).

**Side effects:** none, apart from the abuse-check log row.

## POST /v4/random-jobs

Creates random tasks in a group, assigned to one of its members: staff use it to fill test groups.

* **Auth:** user token. The tasks are created as the member named in `job_user_uuid`, not as the token's user, and `login_user_uuid` is only checked to exist. Nothing checks the staff flag.
* **Used by:** webadmin\_angular (`GroupService.createRandomTasks`, from the random tasks dialog of the [Groups](https://docs.snapfix.com/how-the-apps-work/screens/staff/groups.md) page: `src/app/pages/groups/components/random-tasks-modal/random-tasks-modal.component.ts:45`). The app sends the signed-in staff user as `login_user_uuid` (`src/app/services/group/group.service.ts:132-141`).

**Request** (JSON body)

| Name              | In   | Type    | Required | Rules                                                                                                                                                                                          |
| ----------------- | ---- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business_uuid`   | body | string  | yes      | A live group. Missing: "invalid business"; unknown or deleted: "invalid business data"                                                                                                         |
| `job_user_uuid`   | body | string  | yes      | A live user who is a live member of the group: the tasks' creator and red-status user. Missing: "invalid user"; unknown or deleted: "invalid user data"; not a member: "invalid user business" |
| `login_user_uuid` | body | string  | yes      | A live user. Missing: "invalid user"; unknown or deleted: "invalid user data". Not used further                                                                                                |
| `job_count`       | body | integer | yes      | Above `0`; otherwise "invalid job count". No maximum. A string such as `"5"` passes this check, then fails with `500`                                                                          |

The checks run in this order: an empty body ("invalid params"), the fields above, then the task titles and images on file ("invalid job title", "invalid job image") and the group's `Red` status and `New` sub-status ("invalid status", "invalid sub status") (apipy @ 0e83c85e5a, `model/v4/feature_job.py:2322-2460`).

**Response** `200`: `data` is the list of the new tasks' UUIDs, in creation order.

```json
{ "result": true, "message": "success", "serverTs": 1794387595000, "data": [ "9d2f0c4e-0000-4000-8000-000000000002", "9d2f0c4e-0000-4000-8000-000000000003" ] }
```

**Errors:** `200` with `result` `false` and the messages above; `500` without a JSON body for a `job_count` that is not a number type; `401` "Access token expired".

**Side effects:** for each task (`model/v4/feature_job.py:2463-2565`):

* Inserts a red [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) row with a random title and image from the lists on file, the description "random job generated from web admin", and the member as creator.
* Inserts a "Created Task" [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) row, which writes the member's name into HTML without escaping.
* Looks up the group's notification receivers and queues an "API update required" push to them, once per task.

Each call also writes an abuse-check log row.

## GET /v4/users

Lists users with their contact details, staff notes and group memberships, with paging, filters and sorting: the [Users](https://docs.snapfix.com/how-the-apps-work/screens/staff/users.md) page and the user picker.

* **Auth:** user token. Nothing checks the staff flag, so any signed-in user can list every user with their email address, mobile number, address and staff notes \[[ASK-26](https://github.com/snapfix/docs/blob/main/ASK.md#ask-26-should-users-see-their-own-notes)]. `offset`, `limit` and `sort_field` go into the SQL text as sent.
* **Used by:** webadmin\_angular (`UserService.getUsers`, from the Users page, `src/app/pages/users/users.component.ts:64`, and the user picker, `src/app/components/all-users-select/all-users-select.component.ts:101`). The app sends `fDeleted` `0` unless deleted users are asked for (`src/app/services/user/user.service.ts:59-90`).

**Request** (query)

| Name                                                                                                 | In    | Type    | Required | Rules                                                                                      |
| ---------------------------------------------------------------------------------------------------- | ----- | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `offset`                                                                                             | query | integer | no       | Row offset; default `0`                                                                    |
| `limit`                                                                                              | query | integer | no       | Page size; default `50`. No maximum                                                        |
| `fName`, `fFirstName`, `fLastName`, `fUsername`, `fCountryCode`, `fMobile`, `staff_username`, `uuid` | query | string  | no       | One contains-match each, ignoring case                                                     |
| `fDeleted`                                                                                           | query | integer | no       | `0` or `1`: exact match on the deleted flag. A value that is not a number fails with `500` |
| `sort_field`                                                                                         | query | string  | no       | A column name; default `fCreatedTs`. Not checked against a list                            |
| `sort_type`                                                                                          | query | string  | no       | `-1` or missing sorts descending; anything else ascending                                  |

**Response** `200`: `data` is `{ "total_count": N, "items": [...] }` (apipy @ 0e83c85e5a, `model/v4/t_user.py:18-183`).

| Item field                                                                                                      | Type                    | Meaning                                                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `fUsername`, `staff_username`                                                                           | string or null          | The user's ID, sign-in email and staff username                                                                                                                                                                                                                                     |
| `fName`, `fFirstName`, `fLastName`, `fAddress`                                                                  | string or null          | The names and address                                                                                                                                                                                                                                                               |
| `fCountryCode`, `fMobile`                                                                                       | integer, string or null | The mobile number                                                                                                                                                                                                                                                                   |
| `fNotes`                                                                                                        | string or null          | Staff notes about the user                                                                                                                                                                                                                                                          |
| `fOrigin`, `enum_UserType`                                                                                      | string or null          | Where the user signed up, and the user type                                                                                                                                                                                                                                         |
| `email_verified`, `mobile_verified`, `fLogging`, `fFastLoginProcess`, `fRedDotAlert`, `fRegistered`, `fDeleted` | integer                 | Flags                                                                                                                                                                                                                                                                               |
| `fCreatedTs`, `fModifiedTs`                                                                                     | integer                 | Times, in ms                                                                                                                                                                                                                                                                        |
| `lastLoginTs`                                                                                                   | integer                 | The user row's `fServerTs`: the last time the row changed, not a sign-in time (`model/v4/t_user.py:60`)                                                                                                                                                                             |
| `user_business_item`                                                                                            | array                   | The user's live group memberships, deleted groups and sites included: `uuid` and `name` (the group), `business_uuid` and `business_name` (the site), `uuid_tUser`, `uuid_tUserType`, `user_type` (`admin` for the admin role, else `user`), `parent_deleted` and `business_deleted` |

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "total_count": 1,
    "items": [
      { "uuid": "200", "fUsername": "jane@example.com", "fCountryCode": 44, "fMobile": "7700900123", "staff_username": null, "fName": "Jane Smith", "fFirstName": "Jane", "fLastName": "Smith", "fNotes": null, "fDeleted": 0, "lastLoginTs": 1794300000000, "user_business_item": [ { "uuid": "400", "name": "Front desk", "business_name": "Riverside Hotel", "business_uuid": "123", "uuid_tUser": "200", "uuid_tUserType": "role-100", "user_type": "user", "parent_deleted": 0, "business_deleted": 0 } ] }
    ]
  }
}
```

**Errors:** none in the envelope: the route has no error handling (its `try` is commented out), so "record(s) not found" for an empty page, a bad `sort_field` or `fDeleted`, and a database error all answer `500` without a JSON body (`app.py:2840-2858`); `401` "Access token expired".

**Side effects:** none, apart from the abuse-check log row.

## php-apis actions

What the php-apis sections below share. The shared conventions of every php-apis action are in [README](https://docs.snapfix.com/engineering-reference/api.md); this list adds what holds for the staff actions.

* **Auth:** the mobile dispatcher checks a user token (`Authorization: Bearer`, an authpy access token) while `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)]; with it off, every action needs the shared Basic login (`AUTH_USERNAME`) instead (php-apis @ 238ca4414e, `html/api/snapfix/index.php:383-478`). The Looker actions on the web dispatcher always take the Basic login ([Looker metrics](#post-actionlooker_wau)). The admin app signs in through authpy's `/login`, the customers' sign-in, and sends that access token (webadmin\_angular @ db972390b8, `src/app/services/auth/auth-interceptor/auth.interceptor.ts:28-42`). It sends no `Snapfix` header, which the dispatcher demands while `SNAPFIX_AUTH_ENABLED` is on (`html/api/snapfix/index.php:356-381`, `htmlphp/api/snapfix/class/cognito.functions.php:969-973`), so the admin app works only while that setting is off \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Apart from [create\_temp\_password](#post-actioncreate_temp_password) and the two uncalled `admin_parent_settings` actions, no action here checks the staff flag `fSnapfixWebAdminUser`, so any signed-in user can call them. Each section says which user an action acts on: most take a `user_uuid` from the body and never compare it with the token.
* **Request:** a JSON body (`html/api/snapfix/index.php:246-247`). An empty body gets "Data cannot be blank!".
* **Answers:** errors come back as HTTP `200` with `result` `false` and a message, which for an exception is its text (`:4348-4352`); see [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses).
* **Logs:** the dispatcher stores every request body, and each response under about 100 KB, in the daily request log.
* **Sync queue entry:** the [console definition](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects) applies.

## POST ?action=admin\_check\_user

Finds a user by sign-in email, mobile number or staff username, and says whether that user is in a group: the admin app's group user form checks it before it adds someone.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action reads no user from the token and checks no group role, so any signed-in user can look up any account, and the answer holds every column of the user row.
* **Used by:** webadmin\_angular (`GroupUsersService.checkGroupUser`, `src/app/services/group-users/group-users.service.ts:49`, from the group users modal, `src/app/pages/group-users/components/group-users-modal/group-users-modal.component.ts:53`).

**Request** (JSON body)

| Name                      | In   | Type             | Required           | Rules                                                                                    |
| ------------------------- | ---- | ---------------- | ------------------ | ---------------------------------------------------------------------------------------- |
| `uuid_tBusiness`          | body | string           | yes                | The group. Any group row with that UUID passes, deleted or not; none: "invalid business" |
| `fUsername`               | body | string           | one of the lookups | The sign-in email, matched exactly on live users                                         |
| `fCountryCode`, `fMobile` | body | string or number | one of the lookups | Both are needed, and each must be numeric and above zero. Matched together on live users |
| `staff_username`          | body | string           | one of the lookups | Matched exactly on live users                                                            |

The lookups run in the table's order (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:17056-17104`). Each may match one live user at most, and lookups that match different users give "user duplication found!".

**Response** `200`: `data.user` is the matching user's whole [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row, every column, `fPassword` included. `message` says where the user stands with the group:

* "User exists but not part of this Business": no membership row; `data` has `user` only.
* "User exists but was previously removed from the business": the membership row is deleted; `data.user_business` is that row.
* "User exists and is already part of the business": a live membership; `data.user_business` is that row, and the answer adds `error_type` `ub_failed`.

With several membership rows of which at most one is live, the action takes the first row it reads, so a user with a deleted and a live row can be reported as removed (`:17152-17176`).

```json
{
  "result": true,
  "message": "User exists and is already part of the business",
  "serverTs": 1794387595000,
  "data": {
    "user": { "id": 123, "uuid": "200", "fUsername": "jane@example.com", "fCountryCode": "44", "fMobile": "7700900123", "staff_username": null, "fFirstName": "Jane", "fLastName": "Smith", "fSnapfixWebAdminUser": 0, "fDeleted": 0 },
    "user_business": { "uuid": "310", "uuid_tUser": "200", "uuid_tBusiness": "400", "fDeleted": 0 }
  },
  "error_type": "ub_failed"
}
```

**Errors:** `200` with `result` `false`: "invalid parameters" (no group, or no usable lookup); "invalid business"; "user duplication found!"; "user\_business duplication found" (more than one live membership); "user doesn't exist!" (no live user matches).

**Side effects:** none.

## POST ?action=admin\_create\_assets

Creates assets in one asset register of a site, from a list of titles, statuses and attributes: the admin app's asset upload. The request is checked when it arrives; the assets are written after the answer is sent.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action checks that the site and the register exist and that the register belongs to the site, not who calls, so any signed-in user can add assets to any register.
* **Used by:** webadmin\_angular (`GroupService.uploadAssets`, `src/app/services/group/group.service.ts:129`, from the upload assets modal, `src/app/pages/groups/components/upload-multiple-assets-modal/upload-multiple-assets-modal.component.ts:123`).

**Request** (JSON body)

| Name                  | In   | Type             | Required | Rules                                                                                                                                |
| --------------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `parent_uuid`         | body | string           | yes      | A live site. Missing or blank: "invalid params"; no live site: "invalid parent"                                                      |
| `asset_reg_uuid`      | body | string           | yes      | A live asset register (a group of type `asset`) of that site. Missing or blank: "invalid params"; otherwise "invalid asset register" |
| `assets`              | body | array of objects | yes      | Not an array: "invalid params"                                                                                                       |
| `assets[].title`      | body | string           | yes      | Not blank; no length check                                                                                                           |
| `assets[].status`     | body | string           | yes      | `red`, `amber`, `yellow` or `green`                                                                                                  |
| `assets[].attributes` | body | array of objects | no       | Each object holds one attribute name and its value. An array value is stored as JSON                                                 |

One bad item rejects the whole request with "invalid params" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:43623-43659`).

**Response** `200`, sent before the assets are written:

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

**Errors:** `200` with `result` `false`: "invalid params"; "invalid parent"; "invalid asset register". Errors while the assets are written come after the answer and never reach the caller.

**Side effects:** after the answer, `adminCreateAssets` runs the same checks again and then writes (`html/api/snapfix/index.php:4532-4536`, `class.functions.php:43661-43920`):

* One [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) row per asset in the register (`enum_JobType` 43), with `admin` as the creator and the register's status of that colour, and one "Snapfix Created Asset" [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) entry. Each asset adds one to the site's task count in Firebase.
* One [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md) row per attribute. A name with no rule on the site or the register first gets a text rule on the register in [`tPri_BusinessJobAttributeRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businessjobattributerule.md). Attribute rows and new rules are saved with no creator.
* A [sync queue entry](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects) for each task, chat entry and attribute row; none for a new rule.
* A value that breaks a unique-value rule stops the run, and the assets before it stay created.

## POST ?action=admin\_create\_businesses\_v2

Creates groups in a site from a list of names and addresses: the admin app's group upload. Unlike v1, it writes the groups before it answers.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action checks neither the site nor the caller's role there, so any signed-in user can add groups to any site.
* **Used by:** webadmin\_angular (`GroupService.uploadGroups`, `src/app/services/group/group.service.ts:71`, from the upload groups modal).

**Request** (JSON body)

| Name                                                                                                                     | In   | Type             | Required        | Rules                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------ | ---- | ---------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuid`                                                                                                            | body | string           | yes             | The site. Missing or empty: "invalid params". The action reads the site but ignores the result, so an unknown or deleted site still gets the groups |
| `grouplist`                                                                                                              | body | array of objects | yes             | Missing, not an array or empty: "invalid params"                                                                                                    |
| `grouplist[].fName`, `grouplist[].fAddress`                                                                              | body | string           | yes in practice | The group's name and address. Neither is checked; a missing one is stored empty                                                                     |
| `grouplist[].fImage`, `fGuideJson`, `fContact`, `fPhone`, `fEmail`, `fCustomerType`, `fWebsite`, `sort_order`, `fOrigin` | body | mixed            | no              | Stored on the group as sent                                                                                                                         |

A name and address pair that matches a live group of the site stops the whole request, and the message lists those groups' names: " are already exists!" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:29425-29463`).

**Response** `200`, after the groups are written:

```json
{ "result": true, "message": "Groups created successfully", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false`: "invalid params"; " are already exists!".

**Side effects** (`class.functions.php:29465-29494`), for each group:

* A [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) row in the site, with `admin` as the creator, and a [sync queue entry](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects).
* The group's defaults: a [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md) row, the statuses Red, Amber and Green, and the sub-statuses New, In Progress and Closed, each with a sync queue entry (`:4434-4469`).
* An "API update required" push request to apipy for the group's members, and one more group in the site's Firebase counts. No members are added.

## POST ?action=admin\_create\_checklist

Replaces the checklist of one task with a list of items: the admin app's checklist upload. The old items are marked deleted first.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action acts as the body's `user_uuid`, which must have a live membership of the group, and never compares it with the token's user. It checks no role, so any member can replace any task's checklist in the group.
* **Used by:** webadmin\_angular (`GroupService.uploadChecklist`, `src/app/services/group/group.service.ts:174`, from the upload checklist modal).

**Request** (JSON body)

| Name                                                                                                      | In   | Type             | Required | Rules                                                                        |
| --------------------------------------------------------------------------------------------------------- | ---- | ---------------- | -------- | ---------------------------------------------------------------------------- |
| `user_uuid`                                                                                               | body | string           | yes      | A live member of the group. Saved as the creator and modifier of the items   |
| `group_uuid`                                                                                              | body | string           | yes      | The group                                                                    |
| `job_uuid`                                                                                                | body | string           | yes      | A live task of the group                                                     |
| `checklist`                                                                                               | body | array of objects | yes      | Not an array: "invalid params"; empty: "invalid checklist"                   |
| `checklist[].Name`                                                                                        | body | string           | yes      | The item text. Items without it are skipped                                  |
| `checklist[].sortorder`                                                                                   | body | number           | no       | Saved as `sort_order`                                                        |
| `checklist[].mandatory`                                                                                   | body | number           | no       | Saved as `radioMandatory`; default `0`                                       |
| `checklist[].pass_flag_fail`, `notes`                                                                     | body | number           | no       | Saved as `radioEnable` and `notesEnable`                                     |
| `checklist[].notesValue`, `yesnoEnable`, `starEnabled`, `satisfactionEnabled`, `nfcEnabled`, `nfcScanned` | body | mixed            | no       | Saved under the same names. `yesnoEnable` `1` also sets `yesnoValue` to `-1` |
| `checklist[].nfcSerial`, `timeWindowEnabled`, `timeWindowStartTs`, `timeWindowEndTs`, `item_type`         | body | mixed            | no       | Saved under the same names; defaults `"0"`, `0`, `0`, `0` and `0`            |

**Response** `200`: `todos_created` counts the items saved, that is the items with a `Name`.

```json
{ "result": true, "message": "checklist created successfully", "todos_created": 3, "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:25580-25711`):

* "invalid params": a missing ID, or `checklist` is not an array.
* "invalid checklist": `checklist` is empty.
* "invalid user business association": `user_uuid` has no live membership of the group.
* "invalid job": no live task of the group has `job_uuid`.
* "job todo creation failed": an insert failed. The old items are already deleted by then, and only the items saved before the failure remain.

**Side effects:**

* Marks every [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md) row of the task deleted, then inserts one row per item, each with a [sync queue entry](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects).
* Asks apipy for an "API update required" push to the group's members (`triggerAPIUpdateNotification`, `:39182-39215`), while the queue settings are on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST ?action=admin\_create\_jobs

Creates tasks in a group from a list of titles, as a member of the group: the admin app's task upload. The request is checked when it arrives; the tasks are written after the answer is sent.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action acts as the body's `user_uuid`, which must have a live membership of the group in any role, and never compares it with the token's user.
* **Used by:** webadmin\_angular (`GroupService.uploadTasks`, `src/app/services/group/group.service.ts:100`, from the upload tasks modal, `src/app/pages/groups/components/upload-multiple-tasks-modal/upload-multiple-tasks-modal.component.ts:141`).

**Request** (JSON body)

| Name                                                                                                                                  | In   | Type             | Required | Rules                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `user_uuid`                                                                                                                           | body | string           | yes      | A live member of the group. Saved as the creator and as the red, amber or green user                                                 |
| `group_uuid`                                                                                                                          | body | string           | yes      | The group. It needs a sub-status named "New"                                                                                         |
| `jobs`                                                                                                                                | body | array of objects | yes      | Not an array: "invalid params"; empty: "invalid jobs"                                                                                |
| `jobs[].task_title`                                                                                                                   | body | string           | yes      | Items without it are skipped                                                                                                         |
| `jobs[].status`                                                                                                                       | body | string           | no       | `red`, `amber` (or `yellow`) or `green` set the task's colour and the group's status of that colour. Anything else keeps red         |
| `jobs[].fDescription`, `fLargeTextTitle`, `search_text`, `enum_JobType`, `fJobTs`                                                     | body | mixed            | no       | Saved on the task. Defaults: `search_text` built from the colour, title, reference and description; `enum_JobType` `5`; `fJobTs` now |
| `jobs[].fPriority`, `fPriorityLevel`, `fPriorityNumber`, `fVisible`, `fArchived`, `fLocked`, `fVideoHeader`, `fTodoSignatureRequired` | body | number           | no       | Saved on the task. Defaults `0`, `0`, `1000`, `1`, `0`, `0`, `0` and `0`                                                             |
| `jobs[].checklist`                                                                                                                    | body | array of objects | no       | Checklist items with the fields of [admin\_create\_checklist](#post-actionadmin_create_checklist)                                    |

**Response** `200`: `jobs_created` is the number of items sent, not the number of tasks written.

```json
{ "result": true, "message": "Tasks will be created in the group in sometime", "jobs_created": 2, "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false`: "invalid params"; "invalid jobs"; "invalid user business association"; "invalid sub status" (the group has no "New" sub-status) (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:25160-25210`). "job creation failed" and "job todo creation failed" come from the step after the answer and never reach the caller.

**Side effects:** after the answer, `createJobs` runs the same checks again and then writes, for each task (`html/api/snapfix/index.php:4537-4541`, `class.functions.php:25212-25498`):

* A [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) row with the "New" sub-status, a "Created Task" [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) entry in the member's name, and the member as a follower in [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md). No one is assigned.
* One [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md) row per checklist item.
* A [sync queue entry](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects) for each row, and one more task in the site's Firebase counts.
* At the end, an "API update required" push request for the group, as in [admin\_create\_checklist](#post-actionadmin_create_checklist).

## POST ?action=admin\_create\_mkt\_popup

Creates a marketing popup campaign: the admin app's popup form, when it saves a new popup. The apps show a popup with no sites to every site.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action reads the user from the token's payload without checking its signature, and refuses only a token with no user ("invalid access!"). So any signed-in user can show a popup to every customer.
* **Used by:** webadmin\_angular (`MarketingPopupService.saveMarketingPopup` when there is no popup yet, `src/app/services/marketing-popup/marketing-popup.service.ts:34`, from the marketing popup modal).

**Request** (JSON body)

| Name                                            | In   | Type             | Required       | Rules                                                                                              |
| ----------------------------------------------- | ---- | ---------------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `name`                                          | body | string           | yes            | Trimmed. Missing or blank: "invalid params"                                                        |
| `parent_uuids`                                  | body | array of strings | no             | The sites to show it to, saved as JSON in `parent_uuid_json`. Missing or empty: every site         |
| `ios_disable`, `android_disable`, `web_disable` | body | integer          | no             | `0` or `1`; other values are ignored. Default `0`                                                  |
| `image_portrait_url`, `image_landscape_url`     | body | string           | one of the two | Image URLs, saved as sent. Neither: "invalid image"                                                |
| `campaign_url`, `locale_bcp47`, `timezone_iana` | body | string           | no             | The link the popup opens, a language tag and a time zone; saved as sent, not checked               |
| `campaignStartTs`, `campaignEndTs`              | body | integer          | no             | Epoch ms; saved when above 0                                                                       |
| `mon_startAfterMidnightMs` … `sun_durationMs`   | body | integer          | no             | Fourteen fields: a start after midnight and a duration for each weekday, in ms; saved when above 0 |
| `fActive`                                       | body | integer          | no             | `0` or `1`. Default `1`                                                                            |

**Response** `200`: `data` is the saved [marketing popup](#marketing-popup-object), read back after the insert.

```json
{
  "result": true,
  "message": "Marketting campaign created successfully",
  "serverTs": 1794387595000,
  "data": { "uuid": "123", "name": "Summer offer", "parent_uuid_json": null, "ios_disable": 0, "android_disable": 0, "web_disable": 1, "image_portrait_url": "https://example.com/portrait.png", "timezone_iana": "Europe/London", "fActive": 1, "fDeleted": 0 }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid access!"; "invalid params"; "invalid image" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:43922-44061`).

**Side effects:** inserts a [`mkt_popup`](https://docs.snapfix.com/engineering-reference/db/tables/mkt_popup.md) row with the token's user as the creator. Nothing is pushed: the apps get the popup on their next read of [`get_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-actionget_mkt_popup), which returns live, active popups for the site or for every site (`:44291-44336`).

## POST ?action=admin\_create\_package

Creates a sales package for one site: the Stripe products and prices, the package rows, and an inactive link between the package and the site. The admin app's credit card payment page uses it.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The body's `user_uuid` must be a live user, but the action never compares it with the token's user and checks no sales or staff role.
* **Used by:** webadmin\_angular (`PaymentService.createPackage`, `src/app/services/payment/payment.service.ts:47-55`, from the credit card payment page, `src/app/pages/credit-card-payment/credit-card-payment.component.ts:52`). The page sends the signed-in staff user as both `user_uuid` and `sales_person_uuid`.

**Request** (JSON body)

| Name                | In   | Type   | Required | Rules                                                                                                    |
| ------------------- | ---- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `user_uuid`         | body | string | yes      | A live user, saved as the creator. Unknown: "invalid parent"                                             |
| `parent_uuid`       | body | string | yes      | A live site; otherwise "invalid parent"                                                                  |
| `title`             | body | string | yes      | The package name                                                                                         |
| `currency`          | body | string | yes      | `usd`, `eur`, `gbp` or `inr`, in any case; otherwise "invalid currency"                                  |
| `interval`          | body | string | yes      | `month`, `year` or `day`; otherwise "invalid interval"                                                   |
| `amount`            | body | number | yes      | Above 0; otherwise "invalid amount". It goes to Stripe as sent, so it is in the currency's smallest unit |
| `sales_person_uuid` | body | string | yes      | Saved as the modifier of the site link; not looked up                                                    |

A missing or blank field gives " must be mentioned in the request!", naming each missing field (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/stripe.functions.php:193-206`, `:1186-1225`).

**Response** `200`, with no `data`:

```json
{ "result": true, "message": "package for customer to subscribe is created successfully!", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false`: the missing-field message; "invalid interval"; "invalid currency"; "invalid amount"; "invalid parent" (no live site, or no live user); "invalid package" (the fixed default package row is missing). The package build can also fail, for example with "invalid bundle id" or "paywall\_schema validation failed" (`:777-927`).

**Side effects:** with Stripe's live or test keys, by the server's `MODE`:

* Builds the package in the admin sales bundle, with the default package's paywall schema: a [`package_server`](https://docs.snapfix.com/engineering-reference/db/tables/package_server.md) row, and for each price a Stripe product, a Stripe price and a [`package_server_pricing`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_pricing.md) row (`:777-915`).
* Adds a [`package_server_parent`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_parent.md) row linking the package to the site, inactive, with `stripe_subscription_id` `sales_initiated` (`:1218-1220`).

## POST ?action=admin\_create\_stripe\_product\_v3

Creates a sales package with its Stripe products and prices, and returns the link where a customer buys it: the admin app's Stripe package form and the invoice deal dialog.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The body's `user_uuid` must be a live user; it is never compared with the token's user, and no sales or staff role is checked.
* **Used by:** webadmin\_angular (`PaymentService.createStripeProduct`, `src/app/services/payment/payment.service.ts:100`, from the Stripe payment modal; `InvoiceService.createPackage`, `src/app/services/invoice/invoice.service.ts:157`, from the deal modal, `src/app/pages/invoices/components/deal-modal/deal-modal.component.ts:215`).

**Request** (JSON body)

| Name                                                                           | In   | Type             | Required | Rules                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------ | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`                                                                    | body | string           | yes      | A live user, saved as the creator; otherwise "invalid user"                                                                                                                                                                                                       |
| `package_name`                                                                 | body | string           | yes      | The package name                                                                                                                                                                                                                                                  |
| `price_items`                                                                  | body | array of objects | yes      | Missing, not an array or empty: "invalid price\_items"                                                                                                                                                                                                            |
| `price_items[].name`, `recurring`, `currency`                                  | body | string           | yes      | A missing one: "price\_items error : must be mentioned in the request!". `recurring` is `day`, `month`, `year` or `na` (one-off), else "invalid recurring value for "; `currency` is `usd`, `eur`, `gbp` or `inr` in any case, else "invalid currency value for " |
| `price_items[].amount`                                                         | body | number           | no       | Not below 0, else "invalid amount value for ". It goes to Stripe as sent, in the currency's smallest unit                                                                                                                                                         |
| `price_items[].mandatory`, `qty_editable`, `qty_default`, `qty_min`, `qty_max` | body | number           | no       | Defaults `1`, `0`, `1`, `1` and `999999`                                                                                                                                                                                                                          |
| `fStartTs`, `fEndTs`, `subscription_start_date_ts`                             | body | integer          | no       | Epoch ms, saved on the package                                                                                                                                                                                                                                    |
| `days_past_permitted`, `days_future_permitted`                                 | body | integer          | no       | Days, saved on the package                                                                                                                                                                                                                                        |
| `card_eft`                                                                     | body | string           | no       | Payment types, comma-separated, such as `card,sepa_debit`. The column defaults to `card`                                                                                                                                                                          |
| `stripe_customer_id`                                                           | body | string           | no       | Saved on the package                                                                                                                                                                                                                                              |
| `metadata`                                                                     | body | object           | no       | Saved as the package's `metadata_json`                                                                                                                                                                                                                            |
| `parent_uuid`                                                                  | body | string           | no       | Added to the metadata                                                                                                                                                                                                                                             |
| `origin`                                                                       | body | string           | no       | `webadmin-deals` puts the package in the deals bundle instead of the sales bundle                                                                                                                                                                                 |

A missing `user_uuid` or `package_name` gives " must be mentioned in the request!" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/stripe.functions.php:1275-1362`).

**Response** `200`: `data.package_url` is the package's page, `https://package.snapfix.com/multi/{package uuid}` in live mode and the test package site otherwise.

```json
{
  "result": true,
  "message": "Package created successfully!",
  "serverTs": 1794387595000,
  "data": { "package_url": "https://package.snapfix.com/multi/7c9e6679-7425-40de-944b-e07fc1f90ae7" }
}
```

**Errors:** `200` with `result` `false`: the missing-field message; "invalid price\_items"; "price\_items error : …"; "invalid recurring value for ", "invalid currency value for ", "invalid amount value for "; "invalid user"; "invalid package" (the fixed default package row is missing); and the package build's errors, as in [admin\_create\_package](#post-actionadmin_create_package).

**Side effects:** builds the package as [admin\_create\_package](#post-actionadmin_create_package) does, with these prices, but links it to no site: that insert is commented out (`:1350-1351`). When `stripe_customer_id` is sent and `metadata` has a `hubspot_deal_id`, it also adds a [`tPri_Org_StripeCheckoutUrlLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_stripecheckouturllog.md) row with the deal, company, site, customer and package link (`:837-866`).

## POST ?action=admin\_dashboard\_parents

Returns usage figures for a page of sites: monthly counts of active and unique users, tasks, scheduled tasks, checklist items, time and cost entries, tags and other activity, for a date range. The admin app's account dashboard shows it.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action checks no membership of the sites it reports, so any signed-in user can read every paying site's figures.
* **Used by:** webadmin\_angular (`AnalyticsService.getAccountDashboardAnalyticsData`, `src/app/services/analytics/analytics.service.ts:35`, from the account dashboard).

**Request** (JSON body; every field optional)

| Name                           | In   | Type             | Required | Rules                                                                                                                                                                |
| ------------------------------ | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuids`                 | body | array of strings | no       | The sites. Missing or empty: every live site whose customer type is `fCustomerType`, or, without that, contains "paying". When none matches: "invalid parent\_uuids" |
| `fCustomerType`                | body | string           | no       | Also filters the page of sites                                                                                                                                       |
| `start_date`, `end_date`       | body | string           | no       | `Y-m-d`. Defaults: the first day of the month six months back, and the last day of last month. An end before the start: "invalid dates"                              |
| `sort_by`                      | body | string           | no       | `fName`, `fCustomerType`, `timezone_name` or `fCreatedTs` (default); otherwise "invalid sort\_by"                                                                    |
| `sort_direction`               | body | string           | no       | `ASC` (default) or `DESC`; otherwise "invalid sort\_direction". Read only with `sort_by`                                                                             |
| `offset`                       | body | integer          | no       | A row offset, default `0`                                                                                                                                            |
| `limit`                        | body | integer          | no       | The page size, default `10`, with no maximum                                                                                                                         |
| `search_field`, `search_input` | body | string           | no       | With `search_input`, `search_field` must be `fName`, `fCustomerType` or `timezone_name` ("invalid search" otherwise), and the field must contain the input           |

**Response** `200`: `data` echoes the dates, `fCustomerType`, `search_input`, `search_field` and the `pagination` used, and `items` holds one row per site. Each row has the site's ID, name, image, customer type and its time, first invoice time, time zone and creation time, then, for each of `active_users`, `unique_users`, `tasks`, `scheduled_tasks`, `excl31`, `followassign`, `manual`, `nfc`, `scheduler`, `tags`, `timecost` and `todo`, a list of `{ "month", "count" }` with months as `YYYY-MM`, and its sum in `total_<name>` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:35839-37897`).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "start_date": "2026-05-01",
    "end_date": "2026-10-31",
    "fCustomerType": null,
    "search_input": null,
    "search_field": null,
    "pagination": { "sort_by": "fCreatedTs", "sort_direction": "ASC", "offset": 0, "limit": 10 },
    "items": [
      {
        "parent_uuid": "123",
        "parent_name": "Riverside Hotel",
        "parent_customerType": "paying_customer",
        "parent_timezone": "Europe/London",
        "active_users": [ { "month": "2026-05", "count": 4 }, { "month": "2026-06", "count": 5 } ],
        "total_active_users": 9,
        "tasks": [ { "month": "2026-05", "count": 120 }, { "month": "2026-06", "count": 98 } ],
        "total_tasks": 218
      }
    ]
  }
}
```

**Errors:** `200` with `result` `false`: "invalid sort\_by"; "invalid sort\_direction"; "invalid search"; "invalid parent\_uuids"; "invalid dates"; "invalid parents" (the page holds no site).

**Side effects:** none. The action reads the main database and the metrics database. Without `parent_uuids` and with a large `limit`, one call reads every paying site and the memberships of their active users.

## POST ?action=admin\_delete\_mkt\_popup

Deletes a marketing popup: the admin app's popup list. The row stays with `fDeleted` 1, and the apps stop getting it.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). As in [admin\_create\_mkt\_popup](#post-actionadmin_create_mkt_popup), only a user in the token's payload is needed, so any signed-in user can delete any popup.
* **Used by:** webadmin\_angular (`MarketingPopupService.deleteMarketingPopup`, `src/app/services/marketing-popup/marketing-popup.service.ts:79`, from the marketing popup list).

**Request** (JSON body)

| Name   | In   | Type   | Required | Rules                                                                   |
| ------ | ---- | ------ | -------- | ----------------------------------------------------------------------- |
| `uuid` | body | string | yes      | The popup. Missing: "invalid params"; no live popup: "invalid campaign" |

The dispatcher adds `fDeleted` `1` and runs the update of [admin\_modify\_mkt\_popup](#post-actionadmin_modify_mkt_popup), so any other popup field in the body is changed too (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1054-1059`).

**Response** `200`: `data` is the [marketing popup](#marketing-popup-object) after the change, with `parent_uuid_json` as stored JSON text.

```json
{ "result": true, "message": "Marketting campaign updated successfully", "serverTs": 1794387595000, "data": { "uuid": "123", "name": "Summer offer", "fActive": 1, "fDeleted": 1 } }
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid access!"; "invalid params"; "invalid campaign" (`htmlphp/api/snapfix/class/class.functions.php:44092-44106`).

**Side effects:** sets `fDeleted` `1`, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy` (the token's user) on the [`mkt_popup`](https://docs.snapfix.com/engineering-reference/db/tables/mkt_popup.md) row.

## POST ?action=admin\_guestline\_login

Sends a Guestline login to Guestline's SOAP `LogIn` operation and returns Guestline's answer as it came. The admin app checks a site's Guestline login with it; on success the answer holds the session ID that [admin\_guestline\_statuses](#post-actionadmin_guestline_statuses) needs.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). No site membership is checked.
* **Used by:** webadmin\_angular (`GuestlineService.guestlineLogin`, `src/app/services/guestline/guestline.service.ts:100-109`, from the Guestline modal and the account page's Guestline detail modal, `src/app/pages/account/components/guestline-detail-modal/guestline-detail-modal.component.ts:55`). The app reads the `SessionID` out of the answer (`guestline.service.ts:120-122`).

**Request** (JSON body)

| Name            | In   | Type    | Required        | Rules                                            |
| --------------- | ---- | ------- | --------------- | ------------------------------------------------ |
| `site_id`       | body | string  | yes in practice | Guestline's site ID                              |
| `interface_id`  | body | integer | yes in practice | Guestline's interface ID; the app sends a number |
| `operator_code` | body | string  | yes in practice | Guestline's operator code                        |
| `password`      | body | string  | yes in practice | The Guestline password; not stored               |

The server checks none of the fields and writes each into the SOAP body as sent, without escaping.

**Response** `200`: `data` is Guestline's SOAP answer as raw XML text, or `false` when the connection fails. The action does not read it, so a login that Guestline refuses still gets `result` `true`.

```json
{ "result": true, "message": "success", "serverTs": 1794387595000, "data": "<soap:Envelope>…<LogInResponse>…<SessionID>S-100</SessionID>…</soap:Envelope>" }
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no body). Nothing else (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:40219-40258`).

**Side effects:** one HTTPS call to Guestline's `pmsws.eu.guestline.net` SOAP service, with certificate and host checks turned off (`:40250-40252`). Nothing is stored, but the request log keeps the body with the password.

## POST ?action=admin\_guestline\_statuses

Gets a Guestline session's housekeeping codes from Guestline's SOAP `pmscfg_HouseKeepingCodes` operation and returns the answer as it came. The admin app maps Guestline's housekeeping statuses to Snapfix's with it.

* **Auth:** user token ([php-apis actions](#php-apis-actions)).
* **Used by:** webadmin\_angular (`GuestlineService.getGuestlineStatuses`, `src/app/services/guestline/guestline.service.ts:111-117`, from the Guestline modal, after a login).

**Request** (JSON body)

| Name         | In   | Type   | Required        | Rules                                                                                                                                               |
| ------------ | ---- | ------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id` | body | string | yes in practice | The session ID from [admin\_guestline\_login](#post-actionadmin_guestline_login). Not checked; written into the SOAP body as sent, without escaping |

**Response** `200`: `data` is Guestline's answer as raw XML text, or `false` when the connection fails.

```json
{ "result": true, "message": "success", "serverTs": 1794387595000, "data": "<soap:Envelope>…<pmscfg_HouseKeepingCodesResponse>…</soap:Envelope>" }
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no body). Nothing else (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:40260-40297`).

**Side effects:** one HTTPS call to Guestline, with certificate and host checks turned off (`:40289-40291`). Nothing is stored.

## POST ?action=admin\_list\_mkt\_popup

Lists the marketing popups that are not deleted, active or not, newest first: the admin app's popup list.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action reads no user, not even from the token, and needs no body.
* **Used by:** webadmin\_angular (`MarketingPopupService.getMarketingPopupList`, `src/app/services/marketing-popup/marketing-popup.service.ts:22`, from the marketing popup page).

**Request:** none; a body is ignored.

**Response** `200`: `data` lists the popups with `uuid`, `name`, `ios_disable`, `android_disable`, `web_disable`, `image_portrait_url`, `image_landscape_url`, `timezone_iana`, `campaignStartTs`, `campaignEndTs` and `fActive`. The link, the language, the sites and the weekday windows are left out; [admin\_mkt\_popup\_detail](#post-actionadmin_mkt_popup_detail) has them.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [ { "uuid": "123", "name": "Summer offer", "ios_disable": 0, "android_disable": 0, "web_disable": 1, "image_portrait_url": "https://example.com/portrait.png", "image_landscape_url": null, "timezone_iana": "Europe/London", "campaignStartTs": 1794387595000, "campaignEndTs": 1796979595000, "fActive": 1 } ]
}
```

**Errors:** none of its own (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:44284-44289`).

**Side effects:** none.

## POST ?action=admin\_list\_parent\_user

Lists the admins of one site, or of every site when no site is named, with their contact details and notes: the admin app's business users modal.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). No site membership is checked, and without `parent_uuid` the answer holds every site's admins with their email addresses and phone numbers.
* **Used by:** webadmin\_angular (`UserService.getBusinessAdmins`, `src/app/services/user/user.service.ts:39`, from the business users modal).

**Request** (JSON body, may be empty)

| Name          | In   | Type   | Required | Rules                       |
| ------------- | ---- | ------ | -------- | --------------------------- |
| `parent_uuid` | body | string | no       | Limits the list to one site |

**Response** `200`: one row per site link with `user_type` `admin` and `blocked` `0`, newest first. Deleted links, users and sites are not left out; `deleted_tUserParent` shows a deleted link (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:15384-15402`).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [
    { "uuid_tUserParent": "310", "user_uuid": "200", "parent_uuid": "123", "parent_name": "Riverside Hotel", "user_name": "Jane Smith", "user_firstName": "Jane", "user_lastName": "Smith", "user_fUsername": "jane@example.com", "user_fCountryCode": "44", "user_fMobile": "7700900123", "user_staff_username": null, "user_fImage": null, "notes_tUserParent": null, "deleted_tUserParent": 0, "fCreatedTs": 1794300000000, "fModifiedTs": 1794300000000, "fServerTs": 1794300000000, "user_type": "admin" }
  ]
}
```

**Errors:** `200` with `result` `false`: "no data found" (no row matches).

**Side effects:** none.

## POST ?action=admin\_mkt\_popup\_detail

Gets one marketing popup, with the names of the sites it is meant for: the admin app's popup form, when it opens a popup.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). As in [admin\_create\_mkt\_popup](#post-actionadmin_create_mkt_popup), only a user in the token's payload is needed.
* **Used by:** webadmin\_angular (`MarketingPopupService.getMarketingPopupDetails`, `src/app/services/marketing-popup/marketing-popup.service.ts:75`, from the marketing popup modal).

**Request** (JSON body)

| Name   | In   | Type   | Required | Rules                                                                                            |
| ------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `uuid` | body | string | yes      | The popup. Missing: "invalid params"; no popup: "invalid campaign". Deleted popups are found too |

**Response** `200`: `data` is the [marketing popup](#marketing-popup-object), with `parent_uuid_json` decoded to a list of site IDs and, when it has sites, `parents_json`: the `uuid` and `fName` of each.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": { "uuid": "123", "name": "Summer offer", "parent_uuid_json": ["400"], "parents_json": [ { "uuid": "400", "fName": "Riverside Hotel" } ], "fActive": 1, "fDeleted": 0 }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid access!"; "invalid params"; "invalid campaign" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:44063-44090`).

**Side effects:** none.

## POST ?action=admin\_modify\_gl\_parent

Changes a site's Guestline settings: the Guestline admin, the on/off switch, the Guestline site ID, interface ID and operator code, and the password. The account page's Guestline detail modal saves through it.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). No site membership is checked, so any signed-in user can change any site's Guestline login. The body's `user_uuid` is saved as the modifier, not looked up, and never compared with the token's user.
* **Used by:** webadmin\_angular (`GuestlineService.saveGuestlineParentDetails`, `src/app/services/guestline/guestline.service.ts:35-47`, from the Guestline detail modal). The app sends the signed-in staff user as `user_uuid`.

**Request** (JSON body)

| Name                                             | In   | Type    | Required | Rules                                                                      |
| ------------------------------------------------ | ---- | ------- | -------- | -------------------------------------------------------------------------- |
| `parent_uuid`                                    | body | string  | yes      | A live site with a Guestline row                                           |
| `user_uuid`                                      | body | string  | yes      | Saved as the modifier                                                      |
| `uuid_tUser_Admin`                               | body | string  | no       | The site's Guestline admin; must be a live user, else "invalid user admin" |
| `fEnabled`                                       | body | integer | no       | Switches the Guestline link on or off; saved as sent                       |
| `gl_siteid`, `gl_interfaceid`, `gl_operatorcode` | body | string  | no       | Guestline's IDs; saved as sent                                             |
| `gl_pw`                                          | body | string  | no       | The Guestline password, saved as sent, in plain text                       |

A missing `parent_uuid` or `user_uuid` gives " must be mentioned in the request!". At least one of the other fields must be sent, or "invalid data to update". The action first reads the settings as [admin\_read\_gl\_parent](#post-actionadmin_read_gl_parent) does, so its errors come before any change: a site whose Guestline row has no admin, or a deleted one, cannot be changed at all, not even to set a new admin (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:23516-23565`).

**Response** `200`: `data` is the [Guestline site](#guestline-site-object-php-apis) read again after the change.

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no body; in the older `success` `"0"` form); the missing-field message; "invalid parent"; "guestline info not found!"; "user admin not found!"; "invalid user admin"; "invalid data to update"; the database's error text when the update fails.

**Side effects:** updates the newest [`guestline_parent`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_parent.md) row of the site with the fields sent, and `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy`. No sync queue entry. The request log keeps the body, `gl_pw` included.

## POST ?action=admin\_modify\_mkt\_popup

Changes a marketing popup: the admin app's popup form, when it saves a popup that has a UUID. Only the fields sent change.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). As in [admin\_create\_mkt\_popup](#post-actionadmin_create_mkt_popup), only a user in the token's payload is needed, so any signed-in user can change any popup.
* **Used by:** webadmin\_angular (`MarketingPopupService.saveMarketingPopup` for a popup that exists, `src/app/services/marketing-popup/marketing-popup.service.ts:34`, from the marketing popup modal).

**Request** (JSON body): `uuid`, plus the fields of [admin\_create\_mkt\_popup](#post-actionadmin_create_mkt_popup) and `fDeleted`.

| Name                                                                          | In   | Type                     | Required | Rules                                                                                                                                                                |
| ----------------------------------------------------------------------------- | ---- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                                        | body | string                   | yes      | A live popup. Missing: "invalid params"; otherwise "invalid campaign"                                                                                                |
| `name`, `timezone_iana`                                                       | body | string                   | no       | Changed when not blank                                                                                                                                               |
| `parent_uuids`                                                                | body | array of strings or null | no       | A list replaces the sites. `null`, which the app sends for every site, is stored as `null` and means every site; an empty list is stored as `[]` and matches no site |
| `campaign_url`, `locale_bcp47`, `mon_startAfterMidnightMs` … `sun_durationMs` | body | mixed                    | no       | Changed when sent, also to `null` or empty, which clears them                                                                                                        |
| `campaignStartTs`, `campaignEndTs`                                            | body | integer                  | no       | Changed when above 0                                                                                                                                                 |
| `image_portrait_url`, `image_landscape_url`                                   | body | string                   | no       | Changed when not blank. The popup must keep at least one image, sent or stored, else "invalid image"                                                                 |
| `ios_disable`, `android_disable`, `web_disable`, `fActive`, `fDeleted`        | body | integer                  | no       | `0` or `1`; other values are ignored                                                                                                                                 |

When nothing is left to change: "nothing to update!" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:44092-44282`).

**Response** `200`: `data` is the [marketing popup](#marketing-popup-object) after the change, with `parent_uuid_json` as stored JSON text.

```json
{ "result": true, "message": "Marketting campaign updated successfully", "serverTs": 1794387595000, "data": { "uuid": "123", "name": "Summer offer 2", "parent_uuid_json": "[\"400\"]", "fActive": 1, "fDeleted": 0 } }
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid access!"; "invalid params"; "invalid campaign"; "invalid image"; "nothing to update!".

**Side effects:** updates the [`mkt_popup`](https://docs.snapfix.com/engineering-reference/db/tables/mkt_popup.md) row, with `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy` (the token's user). A deleted popup cannot be changed back.

## POST ?action=admin\_modify\_parent

Changes a site's name, address, customer type, origin, invoice and renewal dates, invoice and sales names, time zone and image, and its email key and email admin. Soft-deletes the site when `fDeleted` is `1`. The admin app's account modal and email service modal save through it.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action checks only that the site exists and is not deleted, so any signed-in user can change, or delete, any site.
* **Used by:** webadmin\_angular (`AccountService.modifyAccount`, `src/app/services/account/account.service.ts:121`, from the account modal; `AccountService.saveEmailService`, `:140`, from the email service modal).

**Request** (JSON body)

| Name                                                                         | In   | Type    | Required | Rules                                                                                                                                                                                                                                                                                                          |
| ---------------------------------------------------------------------------- | ---- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                                       | body | string  | yes      | The site. Missing: "invalid params"; no site: "no parent exists"; a deleted site: "parent seems have been deleted"                                                                                                                                                                                             |
| `email_key`                                                                  | body | string  | no       | Must not belong to another site: "email\_key exists"                                                                                                                                                                                                                                                           |
| `fCustomerType`                                                              | body | string  | no       | One of `internal`, `paying_onboarded`, `paying_new`, `sales_trial`, `churn`, `investor`, `paying_alpha`, `paying_beta`, `alpha`, `beta`, `marketing_influencer`, `paying_customer`, `non_paying_customer`, `test`, `contra`, `0`, `other`, `new_cust` or `investor_probono`; otherwise "invalid fCustomerType" |
| `fCustomerTypeTs`                                                            | body | integer | no       | Epoch ms, read only with `fCustomerType`. Missing or `0`: now                                                                                                                                                                                                                                                  |
| `origin`                                                                     | body | string  | no       | One of `admin`, `snapboard`, `mobile`, `unknown`, `web`, `android`, `ios`, `0` or `webadmin`; otherwise "invalid origin"                                                                                                                                                                                       |
| `email_user_admin_uuid`                                                      | body | string  | no       | A live user. A deleted one: "user account has been deleted". An unknown one stops the action with a PHP type error, an HTTP `500` without a JSON body, so "admin user not exists" never comes back                                                                                                             |
| `fName`, `fAddress`, `fInvoiceName`, `fSalesName`, `timezone_name`, `fImage` | body | string  | no       | Saved as sent                                                                                                                                                                                                                                                                                                  |
| `fFirstInvoiceDateTs`, `fNextRenewalDateTs`                                  | body | integer | no       | Epoch ms, saved as sent                                                                                                                                                                                                                                                                                        |
| `fDeleted`                                                                   | body | integer | no       | Saved as sent; `1` soft-deletes the site                                                                                                                                                                                                                                                                       |

At least one field besides `uuid` must be sent, or "invalid params to update" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:15181-15279`). The type error comes from `sizeof()` on an empty lookup (`:15227-15230`), which PHP 8 refuses; the repo's install guide sets up PHP 8.2 (`README.md:16`).

**Response** `200`: `data` is the site after the change, with `uuid`, `fName`, `fAddress`, `fCustomerType`, `fCustomerTypeTs`, `origin`, `email_key`, `email_user_admin_uuid`, `fDeleted`, `fCreatedTs` and `fModifiedTs`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": { "uuid": "123", "fName": "Riverside Hotel", "fAddress": "1 Quay Street", "fCustomerType": "paying_customer", "fCustomerTypeTs": 1794300000000, "origin": "webadmin", "email_key": null, "email_user_admin_uuid": "200", "fDeleted": 0, "fCreatedTs": 1794300000000, "fModifiedTs": 1794387595000 }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no body; in the older `success` `"0"` form); "invalid params"; "no parent exists"; "parent seems have been deleted"; "email\_key exists"; "invalid fCustomerType"; "invalid origin"; "user account has been deleted"; "invalid params to update"; "Error while updating parent : ". HTTP `500` for an unknown `email_user_admin_uuid`.

**Side effects:** updates the [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) row, with `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy` set to the text `admin`, not a user ID. Queues a [time log row](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects) and a [sync queue entry](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects) for the site.

## POST ?action=admin\_onboard\_parent

Creates a site with its groups and users in one call: the site and its settings, one group per entry, one account per user, and their group memberships. The admin app's onboard page uses it.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action needs a user in the token's payload ("invalid access!"), read without checking the signature, and saves that user as the creator. So any signed-in user can create sites and accounts for any email address or phone number.
* **Used by:** webadmin\_angular (`OnboardService.onboard`, `src/app/services/onboard/onboard.service.ts:54`, from the onboard page, `src/app/pages/onboard/onboard.component.ts:124`).

**Request** (JSON body)

| Name                                    | In   | Type             | Required       | Rules                                                                                                                                                                                                                  |
| --------------------------------------- | ---- | ---------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_name`                           | body | string           | yes            | Missing: "invalid params". A live site with this name: "Business already exists with the name ''"                                                                                                                      |
| `parent_address`                        | body | string           | yes            | Missing: "invalid params"                                                                                                                                                                                              |
| `timezone_name`                         | body | string           | no             | Sent by the admin app's Onboard form, never read: the new site keeps the column default, Europe/Dublin (`htmlphp/api/snapfix/class/class.functions.php:29298-29300`)                                                   |
| `groups`                                | body | array of objects | yes            | Not an array: "invalid params"                                                                                                                                                                                         |
| `groups[].ref_uuid`                     | body | string           | yes            | A reference the users' roles point at; missing: "invalid group reference"                                                                                                                                              |
| `groups[].group_name`                   | body | string           | yes            | Missing: "invalid group name"                                                                                                                                                                                          |
| `groups[].group_template_uuid`          | body | string           | no             | A group to copy the new group from                                                                                                                                                                                     |
| `users`                                 | body | array of objects | yes            | Not an array: "invalid params"                                                                                                                                                                                         |
| `users[].firstname`                     | body | string           | yes            | Missing: "invalid user firstname". Saved as the first name and the name                                                                                                                                                |
| `users[].lastname`                      | body | string           | no             | Saved as the last name                                                                                                                                                                                                 |
| `users[].email`                         | body | string           | email or phone | A valid email, else "invalid user email"; used by a live account: "'' already exists"                                                                                                                                  |
| `users[].countrycode`, `users[].mobile` | body | string           | email or phone | Both numeric, else "invalid user phone", and a valid number, else the phone validator's message; used by a live account: "' `' already exists". With neither email nor phone: "user email or phone is mandatory"`      |
| `users[].password`                      | body | string           | no             | The sign-in password. Without it, the account gets a fixed default password written in the code                                                                                                                        |
| `users[].parent_admin`                  | body | integer          | no             | `1` marks a site admin. At least one user needs it: "atleast one of the users should be mentioned as admin of business"                                                                                                |
| `users[].groups`                        | body | object           | yes            | Maps each group's `ref_uuid` to a role: the admin role ID or the user role ID. Missing: "invalid user group roles"; an unknown reference: "invalid user group reference uuid"; another role: "invalid user group role" |

Every check, the duplicate email and phone checks included, runs before anything is written (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:29190-29296`).

**Response** `200`, with no `data`:

```json
{ "result": true, "message": "New Business created successfully", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid access!"; the messages in the table; "failed to create parent record", "failed to create group('') record" and "failed to create user parent record", which come after part of the site is written.

**Side effects** (`:29297-29422`):

* A [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) row with customer type `admin_quick_onboard` and origin `webadmin`, and a [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md) row with chat on and the AI switches off; a [time log row](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects) and the site's usage counts in Firebase.
* One [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row per user, with a placeholder in the password column and the password's hash and salt in [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) (`:3671-3747`), and a HubSpot contact marked "Webadmin Created" for each.
* One [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) row per group with its default settings, statuses and sub-statuses, as in [admin\_create\_businesses\_v2](#post-actionadmin_create_businesses_v2). A group with `group_template_uuid` is copied from that group instead; the first user given the admin role there becomes its admin, or else the site admin.
* The users' [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) memberships with the roles sent.
* One [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row, an admin row with every site permission on. Only the last user with `parent_admin` `1` gets it: the others, admins included, get no site row.

## POST ?action=admin\_read\_gl\_parent

Gets a site's Guestline settings and its Guestline admin's contact details. The account page's Guestline detail modal reads it. The password is not returned.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). No site membership is checked, so any signed-in user can read any site's Guestline settings and its admin's details.
* **Used by:** webadmin\_angular (`GuestlineService.getGuestlineParentDetails`, `src/app/services/guestline/guestline.service.ts:29-33`, from the Guestline detail modal, `src/app/pages/account/components/guestline-detail-modal/guestline-detail-modal.component.ts:87`).

**Request** (JSON body)

| Name          | In   | Type   | Required | Rules                                                                                              |
| ------------- | ---- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `parent_uuid` | body | string | yes      | A live site. Missing: "parent\_uuid must be mentioned in the request!"; otherwise "invalid parent" |

**Response** `200`: `data` is the [Guestline site](#guestline-site-object-php-apis), from the site's newest [`guestline_parent`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_parent.md) row, deleted or not.

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no body; in the older `success` `"0"` form); the missing-field message; "invalid parent"; "guestline info not found!" (the site has no Guestline row); "user admin not found!" (the row names no admin); "invalid user admin" (the admin is unknown or deleted) (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:23476-23514`).

**Side effects:** none.

## POST ?action=admin\_read\_group\_tag\_settings

Reads a group's first three tag folders and the tags in each: the admin app's upload tags modal shows them before an upload.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action needs a user in the token's payload ("invalid access!"), but not one who belongs to the group, so any signed-in user can read any group's tags.
* **Used by:** webadmin\_angular (`GroupService.getGroupTags`, `src/app/services/group/group.service.ts:143-146`, from the upload tags modal, `src/app/pages/groups/components/upload-tags-modal/upload-tags-modal.component.ts:158`).

**Request** (JSON body)

| Name         | In   | Type   | Required | Rules                                                                                             |
| ------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `group_uuid` | body | string | yes      | A live group. Missing: "group\_uuid must be mentioned in the request!"; otherwise "invalid group" |

**Response** `200`: `data` lists the group's three oldest live [tag folders](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md) (`uuid`, `fName`, `fIcon`), each with `tags`: its live tags (`uuid`, `fName`) by name. A folder with no tags has no `tags` key.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [ { "uuid": "500", "fName": "Location", "fIcon": null, "tags": [ { "uuid": "510", "fName": "Room 101" } ] } ]
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; the missing-field message; "invalid access!"; "invalid group" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:35180-35225`).

**Side effects:** none.

## POST ?action=admin\_read\_jobs

Lists the live tasks of one group, headers only: the admin app's upload checklist modal picks the task to fill from it.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The membership check is commented out, and the `user_uuid` the app sends is not read, so any signed-in user can list any group's tasks (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:25713-25727`).
* **Used by:** webadmin\_angular (`GroupService.getGroupJobs`, `src/app/services/group/group.service.ts:153-160`, from the upload checklist modal, `src/app/pages/groups/components/upload-checklist-modal/upload-checklist-modal.component.ts:125`).

**Request** (JSON body)

| Name         | In   | Type   | Required | Rules                                                        |
| ------------ | ---- | ------ | -------- | ------------------------------------------------------------ |
| `group_uuid` | body | string | yes      | The group; not looked up. Missing or empty: "invalid params" |
| `user_uuid`  | body | string | no       | Sent by the app; not read                                    |

**Response** `200`: one row per live task of the group, with no limit: `job_uuid`, `title`, `business_uuid`, `job_createdts` and `user_uuid` (the creator). An unknown group gives `data: []`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [ { "job_uuid": "700", "title": "Replace bulb", "business_uuid": "400", "job_createdts": 1794300000000, "user_uuid": "200" } ]
}
```

**Errors:** `200`: "Data cannot be blank!" (no body; in the older `success` `"0"` form); "invalid params" with `result` `false` (`html/api/snapfix/index.php:1689-1697`).

**Side effects:** none.

## POST ?action=admin\_read\_pri\_business

Reads group rows, by UUID or by filters: the admin app lists a site's groups with a `uuid_tParent` filter. It is the admin version of the generic table read ([README](https://docs.snapfix.com/engineering-reference/api.md#requests)).

* **Auth:** user token ([php-apis actions](#php-apis-actions)). Nothing limits the rows to the caller's groups: any signed-in user can read any group row, and with no body, the whole table.
* **Used by:** webadmin\_angular (`GroupService.getGroupList`, `src/app/services/group/group.service.ts:32-36`, with `uuid_tParent`), from the groups page, the group users page, the analytics page and the QR management page (`src/app/pages/groups/groups.component.ts:81`, `src/app/pages/group-users/group-users.component.ts:76`, `src/app/pages/analytics/analytics.component.ts:68`, `src/app/pages/qr-management/qr-management.component.ts:182`).

**Request** (JSON body, may be empty)

| Name                          | In   | Type             | Required | Rules                                                                                                                                |
| ----------------------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `uuids`                       | body | array of strings | no       | Reads each group by UUID, one query per UUID. The other keys are then ignored                                                        |
| `uuid_tParent`                | body | string           | no       | The app sends it: the groups of that site, deleted ones included                                                                     |
| `current_max_id`, `max_items` | body | integer          | no       | Paging by row ID: rows with a larger `id`, `max_items` of them (default 20). Without `current_max_id`, every matching row comes back |
| any other key                 | body | mixed            | no       | Filters on the column of that name; `last_updated_ts` filters `fServerTs` from that time on. Key names go into the SQL as they are   |

Without `uuids` and filters, the answer is every row of [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md), with no limit (php-apis @ 238ca4414e, `html/api/snapfix/index.php:4324-4327`; `htmlphp/api/snapfix/class/class.functions.php:1843-1902`, `:2758-2868`).

**Response** `200`: `data` holds whole `tPri_Business` rows, with `fImage` blanked unless it is an `http` link. `current_max_id` is the last row's `id`, or `-1` for a read by `uuids`.

```json
{
  "result": true,
  "current_max_id": 42,
  "message": "Values Found!",
  "serverTs": 1794387595000,
  "data": [ { "id": 42, "uuid": "400", "uuid_tParent": "123", "fName": "Front desk", "fAddress": "1 Quay Street", "fImage": "", "fDeleted": 0, "fCreatedTs": 1794300000000 } ]
}
```

**Errors:** `200` with `result` `false`: "No Record found!" (no row matches).

**Side effects:** none.

## POST ?action=admin\_read\_pri\_user\_business\_v2

Reads the memberships of the named groups, each with the member's names and contact details: the admin app's group users page and two upload modals.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). Nothing limits the groups to the caller's, so any signed-in user can read any group's members with their email addresses and phone numbers.
* **Used by:** webadmin\_angular (`GroupUsersService.getGroupUsers`, `src/app/services/group-users/group-users.service.ts:30-34`), from the group users page, the random tasks modal and the upload tasks modal (`src/app/pages/group-users/group-users.component.ts:114`, `src/app/pages/groups/components/random-tasks-modal/random-tasks-modal.component.ts:55`, `src/app/pages/groups/components/upload-multiple-tasks-modal/upload-multiple-tasks-modal.component.ts:261`). The endpoint list's comment says `APP_HOST = PY`, but the call goes to php-apis.

**Request** (JSON body)

| Name    | In   | Type             | Required | Rules                                                                                                       |
| ------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `uuids` | body | array of strings | no       | Group UUIDs. Without it, the answer is every membership of every group, with no limit. No other key is read |

The query is fixed and the UUIDs go in as parameters (php-apis @ 238ca4414e, `html/api/snapfix/index.php:4320-4323`; `htmlphp/api/snapfix/class/class.functions.php:1846-1867`).

**Response** `200`: one row per [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row of those groups, deleted memberships and users included, with every membership column and the member's `fUsername`, `fCountryCode`, `fMobile`, `staff_username`, `fName`, `fFirstName`, `fLastName`, `fImage` and `fAddress`. `current_max_id` is always `-1`.

```json
{
  "result": true,
  "current_max_id": -1,
  "message": "Values Found!",
  "serverTs": 1794387595000,
  "data": [ { "uuid": "310", "uuid_tUser": "200", "uuid_tBusiness": "400", "uuid_tUserType": "role-100", "perJobViewAll": 1, "fDeleted": 0, "fUsername": "jane@example.com", "fCountryCode": "44", "fMobile": "7700900123", "staff_username": null, "fName": "Jane Smith", "fFirstName": "Jane", "fLastName": "Smith", "fImage": null, "fAddress": null } ]
}
```

**Errors:** `200` with `result` `false`: "No Record found!" (no membership matches).

**Side effects:** none.

## POST ?action=admin\_read\_stripe\_products\_v3

Lists the packages of the admin sales bundle with their prices and package links: the admin app's Stripe payment page. Packages made for deals are in another bundle and are not listed.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). Any signed-in user gets the sales packages, prices and links.
* **Used by:** webadmin\_angular (`PaymentService.getStripeProducts`, `src/app/services/payment/payment.service.ts:58-60`, from the Stripe payment page, `src/app/pages/stripe-payment/stripe-payment.component.ts:120`).

**Request:** none; a body is not read (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1427-1437`).

**Response** `200`: `data` lists the live packages of the bundle as [sales package objects](#sales-package-object).

```json
{
  "result": true,
  "message": "Success!",
  "serverTs": 1794387595000,
  "data": [ { "package_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "package_name": "Riverside plan", "created_at": 1794300000000, "fStartTs": null, "fEndTs": null, "subscription_start_date_ts": null, "days_past_permitted": 7, "days_future_permitted": 30, "card_eft": "card", "package_url": "https://package.snapfix.com/multi/7c9e6679-7425-40de-944b-e07fc1f90ae7", "parents": { "initiated": 0, "active": 0, "inactive": 0 }, "price_items": [ { "uuid": "910", "name": "Monthly plan", "mandatory": 1, "recurring": "month", "currency": "gbp", "amount": 4900, "qty_editable": 0, "qty_default": 1, "qty_min": 1, "qty_max": 999999 } ] } ]
}
```

**Errors:** `200` with `result` `false`: "no packages found!" (the bundle has no live package) (`htmlphp/api/snapfix/class/stripe.functions.php:1364-1403`).

**Side effects:** none.

## POST ?action=admin\_reset\_user\_password

Sets a user's password to the value sent: the admin app's reset password modal.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action checks no relation between the caller and the user, so any signed-in user can set any user's password by UUID. With `JWT_AUTH_ENABLED` off, the shared Basic login is the only check.
* **Used by:** webadmin\_angular (`UserService.resetPassword`, `src/app/services/user/user.service.ts:57`, from the reset password modal).

**Request** (JSON body)

| Name        | In   | Type   | Required | Rules                                                                                               |
| ----------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `user_uuid` | body | string | yes      | A live user; otherwise "Invalid user."                                                              |
| `fPassword` | body | string | yes      | The new password. Only its presence is checked, so an empty string passes; no password rule applies |

**Response** `200`, with no `data`:

```json
{ "result": true, "message": "Password update successful.", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false`: "Invalid parameters." (a field is missing); "Invalid user." (no live user). An empty body gets "Data cannot be blank!" in the older `success` `"0"` form (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2323-2330`; `htmlphp/api/snapfix/class/cognito.functions.php:1003-1063`).

**Side effects:**

* When the user has a [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) row, the newest one gets the new password's hash with its existing salt, and `--disabled--` in its password column. A [`tPri_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) row then records the new password in plain text, next to an empty username field: the username variable is never set.
* When the user has none, a row with a new salt is added, and the user's `temp_password` and `temp_password_required` are set to `1`. No log row.
* The request log keeps the body with the password.

## POST ?action=admin\_save\_parent\_user

Adds site rows for users, or changes or removes them, and sets each one's site role: the account page's business users modal.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). No role on the site is checked, so any signed-in user can make anyone, themselves included, an admin of any site, and the answer lists the site's admins.
* **Used by:** webadmin\_angular (`UserService.saveBusinessUsers`, `src/app/services/user/user.service.ts:48`, from the business users modal).

**Request** (JSON body)

| Name                    | In   | Type             | Required | Rules                                                                                                       |
| ----------------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `parent_uuid`           | body | string           | yes      | The site; not looked up. Empty: "invalid params"                                                            |
| `save_data`             | body | array of objects | yes      | One item per user. Not an array: "invalid params"                                                           |
| `save_data[].user_uuid` | body | string           | yes      | The user. Items without it are skipped and counted in `user_uuid_missed`                                    |
| `save_data[].user_type` | body | string           | no       | `admin` or `normal`. Any other value, and a missing one, saves `admin`, on a change as well as on an insert |
| `save_data[].fNotes`    | body | string           | no       | Saved on the row                                                                                            |
| `save_data[].fDeleted`  | body | integer          | no       | `1` removes the user from the site. Default `0` on an insert                                                |
| `save_data[].uuid`      | body | string           | no       | The ID for a new row; a new ID is made when missing. Not used to find a row                                 |

Each item updates the user's first row for the site, deleted or not, or inserts one when there is none (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:15281-15382`). So an item that only changes the notes, or removes the user, also makes the user an admin.

**Response** `200`: the counts, and in `data.data` the site's admin list as [admin\_list\_parent\_user](#post-actionadmin_list_parent_user) returns it, after the save.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "insert_count": 1,
    "update_count": 0,
    "delete_count": 0,
    "user_uuid_missed": 0,
    "data": [ { "uuid_tUserParent": "310", "user_uuid": "200", "parent_uuid": "123", "parent_name": "Riverside Hotel", "user_fUsername": "jane@example.com", "user_fMobile": "7700900123", "deleted_tUserParent": 0, "user_type": "admin" } ]
  }
}
```

**Errors:** `200` with `result` `false`: "invalid params". An empty body gets "Data cannot be blank!" in the older `success` `"0"` form.

**Side effects:** inserts or updates [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) rows with `admin` as the creator and modifier. A new admin row gets `fAiAutoAssignEnabled`, `fManageTag`, `fCreateNewBusiness`, `fEditTagHeader` and `fManageChecklist` on \[[ASK-267](https://github.com/snapfix/docs/blob/main/ASK.md#ask-267-should-every-way-of-making-someone-a-site-admin-give-enable-ai-auto-assign)]. Each change writes a [sync queue entry](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects).

## POST ?action=admin\_save\_user

Adds a user to a group with the rights sent, and creates the user first when no account matches: the admin app's group user form, after [admin\_check\_user](#post-actionadmin_check_user).

* **Auth:** user token ([php-apis actions](#php-apis-actions)). No role in the group or site is checked, so any signed-in user can add any existing user, themselves included, to any group with any rights, or create an account.
* **Used by:** webadmin\_angular (`GroupUsersService.saveGroupUser`, `src/app/services/group-users/group-users.service.ts:52-79`, from the group users modal). The app sends `fOrigin` `webadmin` and the rights it ticked.

**Request** (JSON body)

| Name                                                                                                                                                                                                                                                                                                                                                                                                    | In   | Type    | Required                             | Rules                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tBusiness`                                                                                                                                                                                                                                                                                                                                                                                        | body | string  | yes                                  | The group                                                                                                                                                                                                                                                 |
| `fUsername`, `staff_username`, `fCountryCode` with `fMobile`                                                                                                                                                                                                                                                                                                                                            | body | string  | one of them                          | Find the account, as in [admin\_check\_user](#post-actionadmin_check_user)                                                                                                                                                                                |
| `uuid_tUserType`                                                                                                                                                                                                                                                                                                                                                                                        | body | string  | yes, unless the user is in the group | The group role ID. A new user without it: "invalid parameters"; an existing user: "invalid user type"                                                                                                                                                     |
| `fFirstName`, `fLastName`                                                                                                                                                                                                                                                                                                                                                                               | body | string  | yes for a new user                   | Without them: "invalid parameters"                                                                                                                                                                                                                        |
| `fName`, `fAddress`, `uuid_tUser`, `uuid_tUserBusiness`                                                                                                                                                                                                                                                                                                                                                 | body | string  | no                                   | Made when missing; `fName` is the first and last name                                                                                                                                                                                                     |
| `fCountryCode`, `fMobile`                                                                                                                                                                                                                                                                                                                                                                               | body | number  | no                                   | For a new user both or neither: "invalid countrycode", "invalid mobile"                                                                                                                                                                                   |
| `fOrigin`                                                                                                                                                                                                                                                                                                                                                                                               | body | string  | no                                   | Default `webadmin`                                                                                                                                                                                                                                        |
| `fPassword`                                                                                                                                                                                                                                                                                                                                                                                             | body | string  | no                                   | A new user's password: hashed into [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md), with `temp_password_required` `1`. Ignored for an existing user                                                  |
| `perJobViewAll`, `perJobCreateNew`, `perJobCreatePlanned`, `perJobToDoCreate`, `perJobToDoEdit`, `perJobToDoDelete`, `perJobDelete`, `perJobArchive`, `perJobReportGenerate`, `perBusCreateNew`, `perBusSettingsScreenAccess`, `perBusSettingsEditUser`, `perBusSettingsEditTag`, `perBusSettingsEditTagHeading`, `perAccessDocuments`, `perAssignUser`, `fActive`, `fArchived`, `fVisible`, `fDeleted` | body | integer | no                                   | The membership's rights. Each value sent replaces its default; the defaults are `1` for `perJobViewAll`, `perJobCreateNew`, `perAccessDocuments`, `perAssignUser`, `fActive` and `fVisible`, `0` for the rest. `perAssignUser` is set only for a new user |

What happens depends on the lookup (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:17211-17381`):

* **No account matches:** creates it, with `temp_password` `1`, `verification_required` `1` and a placeholder in the password column, adds the membership, and adds a `normal` site row when the user has none for the group's site.
* **An account outside the group:** adds the membership. No site row.
* **A live membership:** nothing changes; the answer is `result` `true`, "User exists and is already part of the business", `error_type` `ub_failed`, and the lookup's `data`.
* **A deleted membership:** nothing changes; `result` `false`, "User exists but was previously removed from the business".

**Response** `200`: `data.user` and `data.user_business` are the whole [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) and [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows after the save.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "user": { "uuid": "200", "fUsername": "jane@example.com", "fName": "Jane Smith", "fFirstName": "Jane", "fLastName": "Smith", "fPassword": "--disabled--", "temp_password": 1, "temp_password_required": 1, "fOrigin": "webadmin" },
    "user_business": { "uuid": "310", "uuid_tUser": "200", "uuid_tBusiness": "400", "uuid_tUserType": "role-100", "perJobViewAll": 1, "perBusSettingsEditUser": 0 }
  }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; the lookup's errors ("invalid parameters", "invalid business", "user duplication found!", "user\_business duplication found"); "invalid parameters" (a new user without a role or name); "invalid countrycode"; "invalid mobile"; "invalid user type"; "User exists but was previously removed from the business".

**Side effects:** inserts the [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row, the hash row and, when needed, the [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row for a new user; inserts and updates the [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row; writes [sync queue entries](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects). For a new user in live mode, it also creates or updates a HubSpot contact marked "New parent" (`:35474-35506`).

## POST ?action=admin\_save\_users

Runs [admin\_save\_user](#post-actionadmin_save_user) for each row of a list, one row at a time: the admin app's group user upload.

* **Auth:** as [admin\_save\_user](#post-actionadmin_save_user).
* **Used by:** webadmin\_angular (`GroupUsersService.uploadGroupUsers`, `src/app/services/group-users/group-users.service.ts:109-124`, from the upload group users modal). The app sends each row's group, role, email, password, names, phone and address.

**Request** (JSON body)

| Name    | In   | Type             | Required | Rules                                                                                                                                  |
| ------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `users` | body | array of objects | yes      | Rows with the fields of [admin\_save\_user](#post-actionadmin_save_user). Missing or empty: "invalid parameters". No limit on the rows |

**Response** `200`: `result` is `true` even when every row fails. `data.userCreationFailedData` lists each failed row, sent back whole, its password included, with its `failure_reason`. Rows that saved are not listed. A user who is already in the group counts as failed here, with "User exists and is already part of the business" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:17186-17209`, `:17330-17339`).

```json
{
  "result": true,
  "message": "processed successfully",
  "serverTs": 1794387595000,
  "data": { "userCreationFailedData": [ { "user": { "uuid_tBusiness": "400", "fUsername": "jane@example.com", "fPassword": "<as sent>", "fFirstName": "Jane" }, "failure_reason": "invalid parameters" } ] }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid parameters" (no rows). Each row's own errors go into `userCreationFailedData`.

**Side effects:** the writes of [admin\_save\_user](#post-actionadmin_save_user) for each row, all in one request: several queries per row, and a HubSpot call for each new user in live mode.

## POST ?action=admin\_update\_group\_tag\_settings

Renames a group's tag folders, empties them, and adds tags to them: the admin app's tag upload. The answer is the group's tag settings after the change.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action needs a user in the token's payload ("invalid access!"), saved as the modifier, but not one who belongs to the group.
* **Used by:** webadmin\_angular (`GroupService.saveTags`, `src/app/services/group/group.service.ts:149-151`, from the upload tags modal, `src/app/pages/groups/components/upload-tags-modal/upload-tags-modal.component.ts:144`).

**Request** (JSON body)

| Name                       | In   | Type             | Required | Rules                                                                                             |
| -------------------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `group_uuid`               | body | string           | yes      | A live group. Missing: "group\_uuid must be mentioned in the request!"; otherwise "invalid group" |
| `tag_header`               | body | array of objects | yes      | The folders to change. Missing: "invalid params"                                                  |
| `tag_header[].uuid`        | body | string           | yes      | A live folder of the group, else "invalid tag header ()"                                          |
| `tag_header[].fName`       | body | string           | yes      | The folder's name; a different name renames it                                                    |
| `tag_header[].delete_tags` | body | integer          | no       | `1` marks every tag of the folder deleted before the new ones are added                           |
| `tag_header[].tags`        | body | array of strings | no       | Tag names to add. Blank names and names the folder already has live are skipped                   |

A folder without `uuid` or `fName` gives " must be mentioned in the request!". The folders are processed in order, so an error stops the request after the folders before it are saved (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:35227-35320`).

**Response** `200`: as [admin\_read\_group\_tag\_settings](#post-actionadmin_read_group_tag_settings), read after the change.

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; the missing-field messages; "invalid access!"; "invalid group"; "invalid params"; "invalid tag header ()"; "Error while updating tag header"; "Error while resetting tags"; "Error while creating tags".

**Side effects:** updates [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md) names, marks [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md) rows deleted and inserts new ones, each with a [sync queue entry](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects); then asks apipy for an "API update required" push to the group's members, as in [admin\_create\_checklist](#post-actionadmin_create_checklist).

## POST ?action=create\_snapfix\_package

Creates a paywall package in a marketing bundle, with a Stripe product and price for each price item: the admin app's create paywall package modal.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). `user_uuid` is only checked for presence and saved as the creator; it is never compared with the token's user, and no staff role is checked.
* **Used by:** webadmin\_angular (`PaymentService.createPaywallPackage`, `src/app/services/payment/payment.service.ts:140-142`, from the create paywall package modal).

**Request** (JSON body)

| Name                                                                                               | In   | Type             | Required | Rules                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------- | ---- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`, `name`, `type`, `bundle_id`                                                           | body | string           | yes      | A missing one: " must be mentioned in the request!". `type` is `core` or `supplement`, else "invalid type"; `bundle_id` must be a [`package_marketing_bundle`](https://docs.snapfix.com/engineering-reference/db/tables/package_marketing_bundle.md) row, else "invalid bundle id" |
| `prices`                                                                                           | body | array of objects | yes      | Missing or empty: "invalid price information"                                                                                                                                                                                                                                      |
| `prices[].currency`, `amount`, `interval`                                                          | body | mixed            | yes      | A missing one: "invalid price info". `interval` is `day`, `week`, `month`, `year` or `na`, else "invalid price interval". The amount is only checked for presence and goes to Stripe as sent                                                                                       |
| `prices[].description`, `mandatory`, `qty_editable`, `qty_default`, `qty_min`, `qty_max`           | body | mixed            | no       | As in [admin\_create\_stripe\_product\_v3](#post-actionadmin_create_stripe_product_v3)                                                                                                                                                                                             |
| `paywall_schema`                                                                                   | body | object           | yes      | The package's limits and switches. Missing: "invalid paywall\_schema"; not matching the schema file `paywall_schema_v1.json`: "paywall\_schema validation failed"                                                                                                                  |
| `description`, `card_eft`, `stripe_customer_id`                                                    | body | string           | no       | Saved on the package                                                                                                                                                                                                                                                               |
| `fStartTs`, `fEndTs`, `subscription_start_date_ts`, `days_past_permitted`, `days_future_permitted` | body | integer          | no       | Saved on the package                                                                                                                                                                                                                                                               |
| `metadata`                                                                                         | body | object           | no       | Saved as the package's `metadata_json`                                                                                                                                                                                                                                             |

The checks run in the table's order (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1757-1768`; `htmlphp/api/snapfix/class/stripe.functions.php:777-927`).

**Response** `200`: `data` is the new package as a [paywall package object](#paywall-package-object).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "type": "core", "name": "Team plan", "description": "", "package": { "paywall_version": 1 }, "package_in_use": 0, "currency_supported": ["gbp"], "interval_supported": ["month"], "price": [ { "uuid": "prod_A1", "description": "Team plan", "amount": 4900, "currency": "gbp", "interval": "month", "uuid_package_server": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ] }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; the messages in the table; "Failed to create session" (Stripe returned no product) and "Failed to create price (Currency : , Interval : )" (Stripe returned no price), after the package row is written; "package\_server Creation Error : …" and "package\_server\_pricing Creation Error : …".

**Side effects:** with Stripe's live or test keys, by the server's `MODE`: a [`package_server`](https://docs.snapfix.com/engineering-reference/db/tables/package_server.md) row, then, for each price, a Stripe product, a Stripe price and a [`package_server_pricing`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_pricing.md) row. A checkout link log row as in [admin\_create\_stripe\_product\_v3](#post-actionadmin_create_stripe_product_v3) when `stripe_customer_id` and `metadata.hubspot_deal_id` are sent.

## POST ?action=create\_temp\_password

Creates a one-time temporary password for a user and returns it once: the users page's temporary password button. It is the one action here that requires a Snapfix staff user.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The action decodes the `Authorization` token itself, checks its expiry but not its signature, and requires that the token's user is live and has `fSnapfixWebAdminUser` `1`. So the staff check is only as strong as the dispatcher's token check \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Used by:** webadmin\_angular (`UserService.createTempPassword`, `src/app/services/user/user.service.ts:115-121`, from the users page).

**Request** (JSON body)

| Name        | In   | Type   | Required | Rules                                                                     |
| ----------- | ---- | ------ | -------- | ------------------------------------------------------------------------- |
| `user_uuid` | body | string | yes      | A live user. Missing or empty: "invalid params"; otherwise "invalid user" |

**Response** `200`: `data.temp_password` is a random 20-character password, valid for one sign-in within 600 seconds. Only its hash is stored.

```json
{ "result": true, "message": "success", "serverTs": 1794387595000, "data": { "temp_password": "example-temp-pass-20" } }
```

**Errors:** `200` with `result` `false` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:27210-27292`):

* "Data cannot be blank!": no body.
* "invalid token!": a malformed or expired token.
* "invalid admin token!": no token, or no user in it.
* "invalid admin user": the token's user is not live staff.
* "invalid params"; "invalid user"; "Error in creating password".

**Side effects:** sets `expiryTs` to `-1` on the user's earlier [`tPri_UserHashSalt_Temporary`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt_temporary.md) rows, with the staff user as the modifier, and inserts a new single-use row that expires 600 seconds later. The request log keeps the answer, password included.

## POST ?action=job\_geo\_stats

Lists the tasks of the named groups with their map positions, colours and titles: the admin app's analytics map.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). No membership of the groups is checked, so any signed-in user can read any group's task titles and positions.
* **Used by:** webadmin\_angular (`AnalyticsService.getJobGeoStats`, `src/app/services/analytics/analytics.service.ts:23`, from the analytics page).

**Request** (JSON body)

| Name             | In   | Type             | Required | Rules                                                  |
| ---------------- | ---- | ---------------- | -------- | ------------------------------------------------------ |
| `business_uuids` | body | array of strings | yes      | The groups. Missing or empty: "invalid business uuids" |

**Response** `200`: `data` is keyed by group UUID, in group name order. Each group has `parent_uuid`, `parent_name`, `parent_deleted`, `business_uuid`, `business_name`, `business_deleted` and `jobs`; each task has `uuid`, `name`, `color`, `lat`, `lng` and `deleted`. Deleted tasks, groups and sites are included, with those flags (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:21673-21734`).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "400": { "parent_uuid": "123", "parent_name": "Riverside Hotel", "parent_deleted": 0, "business_uuid": "400", "business_name": "Front desk", "business_deleted": 0, "jobs": [ { "uuid": "700", "name": "Replace bulb", "color": "red", "lat": "51.5000", "lng": "-0.1200", "deleted": 0 } ] }
  }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid business uuids"; "no data found!" (the groups have no task).

**Side effects:** none.

## POST ?action=kpi\_job\_chats\_created\_day

Counts the task chat messages created on each of the last `period` days, and on the `period` days before those, for the groups of the named sites or of every site: the account page's graph modal.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). No membership is checked, so any signed-in user can count any site's messages, and without `parent_uuids` every site's.
* **Used by:** webadmin\_angular (`AccountService.getGraphData`, `src/app/services/account/account.service.ts:124-130`, from the account page's graph modal).

**Request** (JSON body)

| Name                 | In   | Type             | Required | Rules                                                                                        |
| -------------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------- |
| `period`             | body | integer          | yes      | Days; numeric and above 0, else "invalid params"                                             |
| `parent_uuids`       | body | array of strings | no       | The sites: every group of them, deleted ones included. Without it, every group of every site |
| `business_uuids`     | body | array of strings | no       | Groups added to the count                                                                    |
| `uuid_tChatItemType` | body | array of strings | no       | Counts only these chat item types                                                            |

**Response** `200`: `data.result` has the dates (`x_data`, `Y-m-d`, the `period` days before today) and the counts per date (`y_data`); `data.compare` has the same for the `period` days before those. The counts come from the read-only database (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:15898-16022`).

```json
{
  "result": true,
  "message": "success",
  "period_type": "day",
  "request": { "metric_name": "business_job_chats_created_day", "period": 3 },
  "data": {
    "result": { "x_data": ["2026-11-11", "2026-11-12", "2026-11-13"], "y_data": [12, 9, 15] },
    "compare": { "x_data": ["2026-11-08", "2026-11-09", "2026-11-10"], "y_data": [7, 11, 8] }
  },
  "serverTs": 1794387595000
}
```

**Errors:** `200`: "Data cannot be blank!" (no body; in the older `success` `"0"` form); "invalid params" and "no data found!" (no group to count) with `result` `false`.

**Side effects:** none.

## POST ?action=kpi\_job\_chats\_created\_day\_xlsx\_v2\_webadmin

Starts the activity report of the admin app's customer success dashboard: a spreadsheet of task chat messages per day, with each site's risk score, for every live site whose customer type is `paying_customer`, `churn`, `investor_probono` or `sales_trial`. The answer holds the file's future link; the file is built after the answer.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). Any signed-in user can start the report for all those sites, and the link opens without signing in.
* **Used by:** webadmin\_angular (`CsDashboardService.generateActivityReport`, `src/app/services/cs-dashboard/cs-dashboard.service.ts:31`, from the CS dashboard's report modal).

**Request** (JSON body)

| Name                     | In   | Type   | Required | Rules                                                                                                                                                              |
| ------------------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `start_date`, `end_date` | body | string | yes      | Dates. A missing one: "invalid params"; an end before the start: "invalid date range". The number of days comes from the two dates; a `period` sent is overwritten |

No site list is read: the server picks the sites (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:17408-17431`, `:18548-18584`).

**Response** `200`: `data.url` is the file's link in the reports bucket, under a random name. The dispatcher keeps `file_name` for the build and removes it from the answer (`html/api/snapfix/index.php:2343-2355`). Until the build ends, the link does not open.

```json
{ "result": true, "message": "Report will be generated in sometime!", "serverTs": 1794387595000, "data": { "url": "https://reports.example.com/0b7e1f2c-3d4a-4b5c-8d6e-7f8091a2b3c4.xlsx" } }
```

**Errors:** `200`: "Data cannot be blank!" (no body; in the older `success` `"0"` form); "invalid params" and "invalid date range" with `result` `false`. Build errors, such as "invalid parent uuids" when no site matches, come after the answer and never reach the caller.

**Side effects:** after the answer, in the same PHP process (`html/api/snapfix/index.php:4544-4545`): builds the workbook, saves a copy named `Report<time>.xlsx` in the server's `reports/` folder, under the web root in the repo's constants, uploads it to the reports bucket as a public file under the random name, and appends progress lines to a log file next to the code (`class.functions.php:20586-20599`).

## POST ?action=migrate\_job\_v1

Moves a task to another group of the same site: copies the task and its parts into the target group, then marks the original deleted. The admin app's task move page calls it when a task is dropped on the other group, after [migrate\_job\_v1\_validate](#post-actionmigrate_job_v1_validate).

* **Auth:** user token ([php-apis actions](#php-apis-actions)). Nothing ties the caller to either group, and the task is only checked to exist, not to be in the source group, so any signed-in user can move any task of a site into another of its groups.
* **Used by:** webadmin\_angular (`TaskMoveService.migrateJob`, `src/app/services/task-move/task-move.service.ts:34-36`, from the task move page, `src/app/pages/task-move/task-move.component.ts:101`). The page sends `create_tags` and `create_user_business` from the confirm dialog, and no `dest_color`.

**Request** (JSON body)

| Name                       | In   | Type    | Required | Rules                                                                                                                                                                                                                                                            |
| -------------------------- | ---- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business_uuid_source`     | body | string  | yes      | A live group of a live site. Empty: "invalid params"; otherwise "invalid source group"                                                                                                                                                                           |
| `business_uuid_target`     | body | string  | yes      | A live group of a live site, in the same site as the source. Empty: "invalid params"; otherwise "invalid target group"                                                                                                                                           |
| `job_uuid`                 | body | string  | yes      | A live task. Empty: "invalid params"; otherwise "invalid job"                                                                                                                                                                                                    |
| `create_tags`              | body | integer | no       | `1` adds the tags the target group lacks; otherwise those tags are left off the copy. Default `0`                                                                                                                                                                |
| `create_user_business`     | body | integer | no       | `1` adds the task's people who are not in the target group, with their source memberships and roles; otherwise they are left off. Default `0`                                                                                                                    |
| `dest_color`               | body | string  | no       | The target status's colour. It must be the task's colour, else "Moving job between different colors is temporarily not available". `amber` and `yellow` work; `red` and `green` end in a PHP error, an HTTP `500`, because the code calls an undefined `LOWER()` |
| `dest_color_audit_message` | body | integer | no       | `1` adds a chat line "Snapfix changed color to " when the colour changes                                                                                                                                                                                         |

The checks are those of [migrate\_job\_v1\_validate](#post-actionmigrate_job_v1_validate): its first fatal error stops the move with that message, and so does a missing tag heading. Missing tags and people only stop the move when the matching `create_*` flag is `1`, where they are added instead (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:28660-28799`).

**Response** `200`: `data.job_uuid` is the new task, and each count is "copied/found" for that kind of row.

```json
{ "result": true, "message": "success", "serverTs": 1794387595000, "data": { "job_uuid": "701", "todos": "2/2", "tags": "1/1", "notif": "0/0", "followers": "1/2", "assignees": "1/1", "chat": "14/14" } }
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid params"; "invalid source group"; "invalid target group"; "invalid job"; "Source(.) and Target(.) group belongs to different businesses"; "Moving job between different colors is temporarily not available"; "Both groups must have the same Tag Headings (e.g. Location, Equipment, Category) to be able to move a Task from one Group to another Group."; "invalid target business status" (the target has no status of that colour); "Error while creating job …", "Error while creating tag …", "Error while creating user business …".

**Side effects** (`:28700-29188`):

* With the flags, adds [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md) rows and [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows copied from the source memberships, roles and rights included.
* Inserts the new [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) in the target group with the target's status of the colour and no sub-status, since the sub-status lookup is commented out. Copies its checklist items, tags, notifications, followers, assignees, attributes, time and cost rows and chat messages, keeping replies linked to the copied messages. Adds one task to the site's Firebase counts.
* Marks the original task deleted, with `uuid_tUser_ModifiedBy` and `uuid_tUser_DeletedBy` set to the text `admin`. Its child rows stay as they were.
* Writes a [sync queue entry](https://docs.snapfix.com/engineering-reference/api/console.md#common-side-effects) for each row, and asks apipy for an "API update required" push to the members of both groups.

## POST ?action=migrate\_job\_v1\_validate

Compares two groups before a task move and lists what would stop the move and what the move would add to the target group: the task move page shows the warnings in a dialog before it calls [migrate\_job\_v1](#post-actionmigrate_job_v1).

* **Auth:** user token ([php-apis actions](#php-apis-actions)). Nothing ties the caller to the task or either group, and the answer names the task's people who are not in the target group, with their phone numbers or email addresses.
* **Used by:** webadmin\_angular (`TaskMoveService.migrateJobValidate`, `src/app/services/task-move/task-move.service.ts:30-32`, from the task move page, `src/app/pages/task-move/task-move.component.ts:63`).

**Request** (JSON body)

| Name                                           | In   | Type    | Required | Rules                                                                                                        |
| ---------------------------------------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `business_uuid_source`, `business_uuid_target` | body | string  | yes      | Live groups of live sites. Empty: "invalid params"; otherwise "invalid source group", "invalid target group" |
| `job_uuid`                                     | body | string  | yes      | A live task, in any group. Empty: "invalid params"; otherwise "invalid job"                                  |
| `dest_color`                                   | body | string  | no       | Differs from the task's colour: a fatal error                                                                |
| `create_tags`                                  | body | integer | no       | Default `1`; `0` skips the tag check                                                                         |
| `create_user_business`                         | body | integer | no       | Default `1`; `0` skips the people check                                                                      |

**Response** `200`: with no difference, `result` `true` and "Everything(Tag Headers, Tags, Users) fine between groups". Otherwise `result` `false`, "Target business missing with few source business data", and in `data` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:27983-28318`):

* `fatal_errors`: a list of `{ "message" }`: groups in different sites ("Source(.) and Target(.) group belongs to different businesses"), or a `dest_color` that differs from the task's ("Moving job between different colors is temporarily not available"). The comparison runs on after a fatal error.
* `warnings`: a list of `{ "type", "message", "missing_values" }`. `tagheader`: the task's tag headings the target lacks, which [migrate\_job\_v1](#post-actionmigrate_job_v1) refuses. `tag`: the task's tags the target lacks, each with `name` and `target_uuid_tagheader`. `user`: the task's followers, assignees and chat authors who are not in the target group, each with `uuid` and `name`: the first and last name, then the phone number in brackets, or else the username.

```json
{
  "result": false,
  "message": "Target business missing with few source business data",
  "serverTs": 1794387595000,
  "data": {
    "fatal_errors": [],
    "warnings": [
      { "type": "user", "message": "One or more Users in the original Task are not part of the Group where the Task is being moved to. These will now be added to this Group.", "missing_values": [ { "uuid": "200", "name": "Jane Smith (jane@example.com)" }, { "uuid": "201", "name": "Sam Lee (+44 7700900123)" } ] }
    ]
  }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid params"; "invalid source group"; "invalid target group"; "invalid job".

**Side effects:** none.

## POST ?action=paying\_sales\_trial\_account\_users\_webadmin

Starts a spreadsheet of the users of every live site whose customer type is `paying_customer` or `sales_trial`, and answers at once with the file's future link: the CS dashboard's user list report.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). Any signed-in user can produce the file, and its link opens without signing in, so every paying and trial user's contact details can end up in a public file \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)].
* **Used by:** webadmin\_angular (`CsDashboardService.generateUserListReport`, `src/app/services/cs-dashboard/cs-dashboard.service.ts:34-36`, from the CS dashboard, `src/app/pages/cs-dashboard/cs-dashboard.component.ts:109`).

**Request:** none; the body is not read. The dispatcher keeps the random file name for the build, over any `file_name` sent, and removes it from the answer (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2372-2378`).

**Response** `200`: `data.url` is the file's link in the reports bucket, under a random name. The file does not exist yet.

```json
{ "result": true, "message": "Report will be generated in sometime!", "serverTs": 1794387595000, "data": { "url": "https://reports.example.com/0f3c9d2e-7a1b-4c8e-9d5f-2b6a1e4c7d90.xlsx" } }
```

**Errors:** none in the answer. Build errors, such as "no data found!", come after it and never reach the caller.

**Side effects:** after the answer, in the same PHP process (`html/api/snapfix/index.php:4542-4543`), builds the workbook (`htmlphp/api/snapfix/class/class.functions.php:40012-40215`):

* One row per live user with a live membership of a live group of those sites: the site's ID, name and type; the user's ID, email, country code, mobile number, first and last name and alternative name; "Account Admin" or "User"; the last time the user viewed a task, from a scan of the whole task view log; and the site's and the user's creation dates. The "User Last Active in Tasks" column is always "NA": its query is commented out.
* Saves it in the server's `reports/` folder and uploads it to the reports bucket as a public file. Writes no database rows.

## POST ?action=snapfix\_bundles

Lists the paywall's marketing bundles, newest first: the admin app's paywall page.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The list holds no customer data.
* **Used by:** webadmin\_angular (`PaymentService.getPaywallBundles`, `src/app/services/payment/payment.service.ts:132-134`, from the paywall page, `src/app/pages/paywall/paywall.component.ts:97`). It sends no body.

**Request:** none.

**Response** `200`: `data` lists the live [`package_marketing_bundle`](https://docs.snapfix.com/engineering-reference/db/tables/package_marketing_bundle.md) rows with `uuid`, `name`, `description` and `fReadOnly`. The live server leaves out bundles whose ID ends in `_test`; other servers list only those (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/paypack.functions.schema-v1.php:312-320`).

```json
{ "result": true, "message": "success", "serverTs": 1794387595000, "data": [ { "uuid": "bundle-100", "name": "Hospitality", "description": "Hotels and guest houses", "fReadOnly": 0 } ] }
```

**Errors:** none of its own.

**Side effects:** none.

## POST ?action=snapfix\_packages

Lists paywall packages with their schema and prices, for some bundles or for all: the paywall page, for the bundle picked.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). The answer includes each package's schema and prices, and whether a site uses it.
* **Used by:** webadmin\_angular (`PaymentService.getPaywallPackages`, `src/app/services/payment/payment.service.ts:136-138`, from the paywall page, `src/app/pages/paywall/paywall.component.ts:131`). It sends one bundle in `bundle_ids`.

**Request** (JSON body, may be empty)

| Name         | In   | Type             | Required | Rules                                                               |
| ------------ | ---- | ---------------- | -------- | ------------------------------------------------------------------- |
| `bundle_ids` | body | array of strings | no       | Only the packages of these bundles. Missing or empty: every package |

**Response** `200`: `data` lists [paywall package objects](#paywall-package-object), newest first, deleted packages included (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1777-1782`; `htmlphp/api/snapfix/class/paypack.functions.schema-v1.php:38-107`).

**Errors:** `200` with `result` `false`: "invalid packages" (no package matches).

**Side effects:** none.

## POST ?action=update\_package\_schema

Replaces a package's paywall schema, the limits and switches it grants: the paywall page's edit dialog.

* **Auth:** user token ([php-apis actions](#php-apis-actions)). `user_uuid` comes from the body, is only saved as the modifier and is never compared with the token's user, so any signed-in user can rewrite any package's schema.
* **Used by:** webadmin\_angular (`PaymentService.updatePaywallPackage`, `src/app/services/payment/payment.service.ts:144-146`, from the edit paywall package modal, `src/app/pages/paywall/components/edit-paywall-package-modal/edit-paywall-package-modal.component.ts:63`).

**Request** (JSON body)

| Name                  | In   | Type   | Required | Rules                                                                                                                                                                                                                                                               |
| --------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paywall_schema`      | body | object | yes      | The new schema. Missing or `null`: "invalid params". Checked against the schema file `paywall_schema_v1.json`, which is not in the repo \[[ASK-197](https://github.com/snapfix/docs/blob/main/ASK.md#ask-197-is-paywall_schema_v1json-deployed-on-the-api-servers)] |
| `package_server_uuid` | body | string | yes      | The package. Missing or blank: "invalid params"; no package: "invalid packages"                                                                                                                                                                                     |
| `user_uuid`           | body | string | yes      | Saved as the modifier. Missing: "invalid params"                                                                                                                                                                                                                    |

**Response** `200`: the changed package as a [paywall package object](#paywall-package-object). A schema that fails the check gets `result` `false`, "invalid paywall schema", and `debug`, a list of the failed checks (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/stripe.functions.php:1012-1044`).

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "invalid params"; "invalid packages"; "invalid paywall schema", with `debug`; "package\_server update Error : ".

**Side effects:** replaces the `package` JSON of the [`package_server`](https://docs.snapfix.com/engineering-reference/db/tables/package_server.md) row and sets `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy`. No history is kept, and Stripe is not called.

## POST ?action=looker\_au\_wow

Looker metric: active users per site, week over week, for the last 12 weeks, for the sites in `customers` or the sites that match the filter (paying customers by default). The answer names the sites.

* **Auth:** the shared Basic login (`AUTH_USERNAME`) only. The web dispatcher puts every Looker action on its open list, so no token is checked, but the Basic login still is (php-apis @ 238ca4414e, `html/api/snapfix/web/index.php:441`, `:507-531`).
* **Used by:** authpy (`featurePhpApi.lookerActiveUsersWeekOverWeek`, authpy @ 5d5758661c, `model/feature_php_api.py:297-301`), behind its `/looker/au-wow` route. authpy sends `{ "data": <its request>, "SP_FORWARDED_FOR": <the X-Forwarded-For header> }` with the Basic login (`:37-48`). Which tool calls authpy's Looker routes is not in the repos \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].

**Request** (JSON body)

| Name                                     | In   | Type             | Required | Rules                                                                                                                |
| ---------------------------------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `data`                                   | body | object           | yes      | The metric's options. Missing: `status` `error`, "invalid params"                                                    |
| `data.customers`                         | body | array of strings | no       | Site IDs to report on, instead of the filter. Not checked, and written into the SQL text as they are                 |
| `data.filter`                            | body | object           | no       | Not an object: "Bad Request"                                                                                         |
| `data.filter.ages`                       | body | array of strings | no       | `<60 days`, `>60 days` or `All time`, by site creation date. Not an array: "validation on filter.age failed"         |
| `data.filter.types`                      | body | array of strings | no       | Customer types; default `paying_customer`; `all` lifts the filter. Not an array: "validation on filter.types failed" |
| `data.filter.industries`                 | body | array of strings | no       | Industry names from the sites' registration notes. Not an array: "validation on filter.industries failed"            |
| `data.filter.countries`                  | body | array of strings | no       | Country codes of the sites' addresses. Not an array: "validation on filter.countries failed"                         |
| `data.page`, `data.limit`, `data.offset` | body | integer          | no       | Read only in a branch that never runs, so they change nothing                                                        |
| `data.fetchAvailableFilterValues`        | body | boolean          | no       | Default `true`, which adds `availableFilter` at the cost of three more queries                                       |
| `data.log`                               | body | integer          | no       | `1` appends the SQL text to `looker-query.log` next to the code                                                      |
| `SP_FORWARDED_FOR`                       | body | string           | no       | The client's address, added by authpy                                                                                |

The filter takes sites by those rules, deleted ones included, and "metrics not found" when none matches (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:16-135`, `:885-1097`).

**Response** `200`: a [Looker metric object](#looker-metric-object), "Active Users - Week Over Week", `chartType` "Table", with `data.customers`: per site, its `accountName` (`uuid`, `fName`, `fCustomerType`, `fImage`) and one `metrics` row per week, with `xHint`, `xValue`, `yHint`, `yVolume` and `yWOW` (the change on the week before, in percent).

**Errors:** `200` with `status` `error`: "invalid params"; "Bad Request"; the filter validation messages; "metrics not found"; the text of any other exception, which can be a database error.

**Side effects:** none on the database. Reads the site table on the read-write connection and the metrics database.

## POST ?action=looker\_churnrate

Looker metric: the monthly churn rate over all sites, for the last 18 months, from the site history table. No filter applies.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerChurnRateMonthly`, authpy @ 5d5758661c, `model/feature_php_api.py:309-313`), behind its `/looker/churnrate-monthly` route.

**Request** (JSON body): `data` (required; missing: `status` `error`, "invalid params"). `data.filter` is only echoed back in `appliedFilter`; `data.log` `1` logs the SQL text, as for [looker\_au\_wow](#post-actionlooker_au_wow).

**Response** `200`: a [Looker metric object](#looker-metric-object), "Customer monthly Churn Percent", `chartType` "Line Chart", with one `data.metrics` row per month: `xHint` (the month), `xValue`, `yCumulativePayingCustomers`, `yCumulativeChurnCustomers` and `yChurnRate` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:1449-1531`).

**Errors:** `200` with `status` `error`: "invalid params"; the text of any exception.

**Side effects:** none on the database. Reads [`time_tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/time_tpri_parent.md) on the read-write connection.

## POST ?action=looker\_tc\_wow

Looker metric: tasks created per site, week over week, for the last 12 weeks, for the sites in `customers` or the sites that match the filter. The answer names the sites.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerTasksCreatedWeekOverWeek`, authpy @ 5d5758661c, `model/feature_php_api.py:303-307`), behind its `/looker/tc-wow` route.

**Request** (JSON body): as for [looker\_au\_wow](#post-actionlooker_au_wow), `customers` going into the SQL text too, and `page`, `limit` and `offset` changing nothing.

**Response** `200`: a [Looker metric object](#looker-metric-object), "Tasks Created - Week Over Week", `chartType` "Table", with `data.customers` as for [looker\_au\_wow](#post-actionlooker_au_wow); each `metrics` row has `xHint`, `xValue`, `yHint` "Tasks Created", `yVolume` and `yWOW` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:1099-1351`).

**Errors** and **side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## POST ?action=looker\_wau

Looker metric: weekly active users, summed over the sites that match the filter (paying customers by default).

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerWeeklyActiveUsers` and `lookerWeeklyActiveUsersSample`, authpy @ 5d5758661c, `model/feature_php_api.py:245-249`, `:269-274`), behind its `/looker/wau` and `/looker/wau-sample` routes. The sample call sets `dev`.

**Request** (JSON body): `data`, with the `filter` fields of [looker\_au\_wow](#post-actionlooker_au_wow) (no `customers`), `fetchAvailableFilterValues` and `log`, and:

| Name                                           | In   | Type   | Required | Rules                                                                                       |
| ---------------------------------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `data.filter.startDate`, `data.filter.endDate` | body | string | no       | `Y-m-d`, sent together. Without them, the eight weeks up to last Sunday                     |
| `data.dev`                                     | body | any    | no       | Any value but `null`, even `false`, returns the fixed sample file `wau-sample.json` instead |

**Response** `200`: a [Looker metric object](#looker-metric-object), "Weekly Active Users Report", `chartType` "Line Chart", with one `data.metrics` row per week: `xHint` (the dates), `xHintV2` (a label such as "Week of Sep 14, 2026 (Week 38 of 2026)"), `xValue`, `yHint` "Active Users" and `yValue` (php-apis @ 238ca4414e, `html/api/snapfix/web/index.php:996-1008`; `htmlphp/api/snapfix/class/looker.functions.php:185-279`; `htmlphp/api/snapfix/class/looker_dev.functions.php:13-17`).

**Errors:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

**Side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## POST ?action=looker\_wau\_avg\_median

Looker metric: the weekly average and median of active users per site, over the sites that match the filter.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerWeeklyAverageMedianActiveUsers` and its sample variant, authpy @ 5d5758661c, `model/feature_php_api.py:257-261`, `:283-288`), behind its `/looker/wau-avg-median` and `/looker/wau-avg-median-sample` routes.

**Request** (JSON body): as for [looker\_wau](#post-actionlooker_wau); `dev` returns `wau-avg-median-sample.json`. A leftover debug key in `data`, named after a developer, sent with any value, prints the first week's raw active user counts per site and ends the request (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:422-425`).

**Response** `200`: a [Looker metric object](#looker-metric-object), "Average and Median Weekly Active Users", `chartType` "Combined Line Chart", with one `data.metrics` row per week: `xHint`, `xValue`, `yHint`, `yAverage` and `yMedian` (`:287-463`).

**Errors:** as for [looker\_au\_wow](#post-actionlooker_au_wow), except that an exception comes back as `result` `false` with its text: the dispatcher's list of Looker actions names this one `looker_wau_avg` (`html/api/snapfix/web/index.php:2528-2532`).

**Side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## POST ?action=looker\_wau\_percent

Looker metric: each site's weekly active users as a percent of its users, for the sites in `customers` or the sites that match the filter. The answer names the sites.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerWeeklyActiveUsersPercent`, authpy @ 5d5758661c, `model/feature_php_api.py:315-319`), behind its `/looker/wau-percent` route.

**Request** (JSON body): as for [looker\_au\_wow](#post-actionlooker_au_wow), with `customers` going into the SQL text, plus `filter.startDate` and `filter.endDate` as for [looker\_wau](#post-actionlooker_wau). `data.dev`, with any value but `null`, ends in a PHP error, an HTTP `500`, because the sample class has no such metric.

**Response** `200`: a [Looker metric object](#looker-metric-object), "Active Users Percent", `chartType` "Table", with `data.customers`; each `metrics` row has `xHint`, `customerName`, `customerUUID`, `weekStartDate`, `weekEndDate`, `xValue`, `yHint` "Active Users Percent", `yTotalUsers`, `yActiveUsers` and `yActiveUsersPercent` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:1533-1908`).

**Errors** and **side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## POST ?action=looker\_wc\_activity

Looker metric: weekly checklist activity per site, for the sites in `customers` or the sites that match the filter. The answer names the sites.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerWeeklyChecklistActivity`, authpy @ 5d5758661c, `model/feature_php_api.py:327-331`), behind its `/looker/wc-activity` route.

**Request** (JSON body): as for [looker\_au\_wow](#post-actionlooker_au_wow), with `customers`, plus `filter.startDate` and `filter.endDate`. `dev` changes nothing here.

**Response** `200`: a [Looker metric object](#looker-metric-object), `chartType` "Table", with `data.customers`: each site's `accountName` and weekly `metrics`. Its title is "Weekly Checklist Count Dev", the same as [looker\_wc\_count](#post-actionlooker_wc_count)'s (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:2081-2272`).

**Errors** and **side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## POST ?action=looker\_wc\_count

Looker metric: the weekly checklist count per site, for the sites in `customers` or the sites that match the filter. The answer names the sites.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerWeeklyChecklistCount`, authpy @ 5d5758661c, `model/feature_php_api.py:321-325`), behind its `/looker/wc-count` route.

**Request** (JSON body): as for [looker\_wc\_activity](#post-actionlooker_wc_activity).

**Response** `200`: a [Looker metric object](#looker-metric-object), "Weekly Checklist Count Dev", `chartType` "Table", with `data.customers`; the rows' `yHint` is "Checklist Count" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:1910-2079`).

**Errors** and **side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## POST ?action=looker\_wgau\_percent

Looker metric: weekly generic active users as a percent, for the sites in `customers` or the sites that match the filter. The answer names the sites.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerWeeklyGenericActiveUsersPercent`, authpy @ 5d5758661c, `model/feature_php_api.py:333-337`), behind its `/looker/wgau-percent` route.

**Request** (JSON body): as for [looker\_wau\_percent](#post-actionlooker_wau_percent), `customers` going into the SQL text, and `dev` ending in an HTTP `500`.

**Response** `200`: a [Looker metric object](#looker-metric-object), "High level Active Users Percent", `chartType` "Table", with `data.customers` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:2274-2591`).

**Errors:** as for [looker\_au\_wow](#post-actionlooker_au_wow), except that an exception comes back as `result` `false` with its text, since the dispatcher's list of Looker actions leaves this one out.

**Side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## POST ?action=looker\_wtc

Looker metric: weekly tasks created, summed over the sites that match the filter.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerWeeklyTasksCreated` and `lookerWeeklyTasksCreatedSample`, authpy @ 5d5758661c, `model/feature_php_api.py:251-255`, `:276-281`), behind its `/looker/wtc` and `/looker/wtc-sample` routes.

**Request** (JSON body): as for [looker\_wau](#post-actionlooker_wau); `dev` returns `wtc-sample.json`.

**Response** `200`: a [Looker metric object](#looker-metric-object), "Human Tasks Created Weekly", `chartType` "Line Chart", with one `data.metrics` row per week: `xHint`, `xValue`, `yHint` "Tasks Created" and `yValue` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:465-648`).

**Errors** and **side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## POST ?action=looker\_wtc\_avg\_median

Looker metric: the weekly average and median of tasks created per site, over the sites that match the filter.

* **Auth:** the shared Basic login only, as for [looker\_au\_wow](#post-actionlooker_au_wow).
* **Used by:** authpy (`featurePhpApi.lookerWeeklyAverageMedianTasksCreated` and its sample variant, authpy @ 5d5758661c, `model/feature_php_api.py:263-267`, `:290-295`), behind its `/looker/wtc-avg-median` and `/looker/wtc-avg-median-sample` routes.

**Request** (JSON body): as for [looker\_wau](#post-actionlooker_wau); `dev` returns `wtc-avg-median-sample.json`.

**Response** `200`: a [Looker metric object](#looker-metric-object), "Average and Median Human Tasks Created Weekly", `chartType` "Combined Line Chart", with one `data.metrics` row per week: `xHint`, `xValue`, `yHint`, `yAverage` and `yMedian` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php:650-883`).

**Errors:** as for [looker\_wau\_avg\_median](#post-actionlooker_wau_avg_median): an exception comes back as `result` `false`, the list naming this action `looker_wtc_avg`.

**Side effects:** as for [looker\_au\_wow](#post-actionlooker_au_wow).

## Organization object

An organization in [GET /v1/admin/organizations](#get-v1adminorganizations), and in the answers of the change and connect routes (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/Admin/OrgResource.php`).

| Field          | Type            | Meaning                                                                                                                |
| -------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `name` | string          | The organization's ID and name (`fName`)                                                                               |
| `accounts`     | object          | `hubspot`, `stripe` and `xero`: the UUID of the linked account row, or `null`                                          |
| `parentsCount` | integer or null | The number of live sites linked to it. Filled on the list only; `null` in the answers of the change and connect routes |

## Organization detail object

An organization with its accounts and sites, in [GET /v1/admin/organizations/{uuid}](#get-v1adminorganizationsuuid) and [POST /v1/admin/organizations](#post-v1adminorganizations) (`app/Http/Resources/v1/Admin/OrgDetailedResource.php`).

| Field                                                                           | Type            | Meaning                                                                                                                                                                 |
| ------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `name`                                                                  | string          | The organization's ID and name                                                                                                                                          |
| `image`, `type`, `address`, `postalCode`, `city`, `country`, `subscriptionType` | string or null  | `fImage`, `fOrgType`, `fAddress`, `fPostalCode`, `fCity`, `fCountry` and `fSubscriptionType`                                                                            |
| `firstInvoiceDate`, `nextRenewalDate`                                           | integer or null | `fFirstInvoiceDateTs` and `fNextRenewalDateTs`, in ms                                                                                                                   |
| `accounts`                                                                      | object or array | `hubspot`, `stripe` and `xero`, each an [organization account object](#organization-account-object), present only when the linked account row exists; `[]` when none is |
| `parents`                                                                       | array           | The organization's live sites, as [admin site objects](#admin-site-object) without `parentAddress`                                                                      |

## Organization account object

A HubSpot, Stripe or Xero account, in [GET /v1/admin/organizations/account/{name}](#get-v1adminorganizationsaccountname) and in an organization's `accounts` (`app/Http/Resources/v1/Admin/OrgAccountResource.php`, `HubspotOrgAccountResource.php`, `StripeOrgAccountResource.php`, `XeroOrgAccountResource.php`).

| Field         | Type   | Meaning                                                                                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`        | string | The account row's ID; the connect routes take it as `accountId`                                                                                    |
| `accountId`   | string | The account's ID in its own system: the HubSpot deal ID (`hs_id`), the Stripe customer ID (`stripe_id`) or the Xero contact ID (`xero_contact_id`) |
| `accountName` | string | The deal name, the Stripe customer name or the Xero contact name                                                                                   |

## Admin site object

A site as the admin routes return it: in [POST /v1/admin/parents](#post-v1adminparents), [GET /v1/admin/parents/{uuid}](#get-v1adminparentsuuid), the connect and disconnect answers, and an organization's `parents` (`app/Http/Resources/v1/Admin/ParentResource.php`).

| Field                                                                 | Type                            | Meaning                                                                                                                                                                         |
| --------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `orgUuid`                                                     | string or null                  | The site's ID, and the organization it is linked to                                                                                                                             |
| `name`                                                                | string                          | The site's name (`fName`)                                                                                                                                                       |
| `image`, `address`, `emailKey`                                        | string or null                  | The image URL, the free-text address (`fAddress`) and the email key; `null` when empty                                                                                          |
| `customerType`, `customerTypeTs`                                      | string or null, integer or null | The customer type, and when it was set, in ms                                                                                                                                   |
| `riskScore`, `riskScoreTs`, `firstInvoiceDateTs`, `nextRenewalDateTs` | integer or null                 | Stored values; times in ms                                                                                                                                                      |
| `origin`, `timezoneName`, `defaultCurrency`                           | string                          | Left out when the site has none                                                                                                                                                 |
| `userCount`, `groupCount`, `jobCount`                                 | integer                         | Always `0` here: these routes do not load the counts                                                                                                                            |
| `deleted`                                                             | integer or null                 | `null` for a live site                                                                                                                                                          |
| `createdTs`, `modifiedTs`                                             | string                          | ISO 8601 date-times, such as `2026-11-14T08:35:00.000000Z`; left out when empty                                                                                                 |
| `parentAddress`                                                       | object                          | On the create and get routes only: the newest live basic address, as a [site address object](https://docs.snapfix.com/engineering-reference/api/console.md#site-address-object) |

## QR form object

A QR form in the [QR form routes](#get-v1adminqr-form) (`app/Http/Resources/v1/Admin/QrFormResource.php`). `inAppVisible` and `hardcodedJobJson` are not returned.

| Field                                                   | Type                    | Meaning                                                               |
| ------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------- |
| `uuid`, `businessUuid`                                  | string                  | The form's ID and its group                                           |
| `dynamicFormJson`                                       | object                  | The form's pages and components, as saved                             |
| `inAppTitle`, `posterTitle`, `posterDescription`        | string                  | The titles and the poster text                                        |
| `formEnum`                                              | string                  | The form type: one of the four types, or any string an update stored  |
| `posterHackerWarning`, `posterHackerWarningDescription` | integer, string or null | The warning switch and its text                                       |
| `createdTs`, `modifiedTs`                               | string or null          | ISO 8601 date-times without fractions, such as `2026-11-14T08:35:00Z` |
| `createdByUserUuid`, `modifiedByUserUuid`               | string or null          | The staff users who created the form and changed it last              |

## Survey object

A pre-registration survey in the [survey routes](#get-v1adminsurvey) (`app/Http/Resources/v1/Admin/PreRegSurveyResource.php`).

| Field                                     | Type           | Meaning                                                                                     |
| ----------------------------------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `uuid`                                    | string         | The survey's ID                                                                             |
| `dynamicFormJson`                         | object         | The form, as saved                                                                          |
| `startTs`, `endTs`                        | integer        | When the survey is open, in ms                                                              |
| `ipFilterJson`                            | object or null | The filters, as saved. `countryCode` lists the countries; an empty list means every country |
| `deviceType`                              | array or null  | `android`, `ios` and `web`; an empty list means every device                                |
| `inActive`                                | integer        | `1` when the survey is switched off                                                         |
| `createdTs`, `modifiedTs`                 | string or null | ISO 8601 date-times without fractions                                                       |
| `createdByUserUuid`, `modifiedByUserUuid` | string or null | The staff users who created the survey and changed it last                                  |

## GoCardless customer object

The answer of [GET /v1/admin/sales/gocardless-customer](#get-v1adminsalesgocardless-customer) (`app/Http/Resources/v1/Admin/GoCardlessCustomerResource.php`, `GoCardlessMandateResource.php`).

| Field             | Type             | Meaning                                                                                                       |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `customerId`      | string           | The GoCardless customer ID                                                                                    |
| `activeMandate`   | as sent, or null | The service's `active_mandate`; the admin app treats it as a yes or no                                        |
| `activeMandateId` | string or null   | The active mandate's ID                                                                                       |
| `createdAt`       | string or null   | The service's `created_at`                                                                                    |
| `allMandates`     | array            | The mandates, each with `id`, `status`, `createdAt`, `snapfixStatus` and `snapfixInstruction`; `[]` when none |
| `devNote`         | string           | Only when the service sends `devnote`                                                                         |

## GoCardless payment object

A payment as the org mapping service returns it, passed through by [POST /v1/admin/sales/company-gocardless-checkout](#post-v1adminsalescompany-gocardless-checkout) and [POST /v1/admin/sales/gocardless-payments](#post-v1adminsalesgocardless-payments). The fields below are those the admin app reads (webadmin\_angular @ db972390b8, `src/app/models/invocie/invoice.model.ts:169-179`); the checkout route also reads `id` and, without `charge_date`, `start_date`.

| Field                           | Type   | Meaning                                                    |
| ------------------------------- | ------ | ---------------------------------------------------------- |
| `id`                            | string | The GoCardless payment ID                                  |
| `created_at`, `charge_date`     | string | When the payment was made, and when it is charged          |
| `amount`                        | number | The amount in minor units: the admin app divides it by 100 |
| `currency`                      | string | The currency code                                          |
| `name`, `description`           | string | The product name and the payment's text                    |
| `metadata.hubspot_line_item_id` | string | The HubSpot line item the payment is for                   |

## Onboarding log object

An onboarding record, in [POST /v1/admin/sales/onboarding](#post-v1adminsalesonboarding) and in a deal's `orgOnboardingLog` (`app/Http/Resources/v1/Admin/OrgOnboardingLogResource.php`, `app/Models/OrgOnboardingLogModel.php:15-22`).

| Field                              | Type            | Meaning                                                                                                                                                                                                                                                |
| ---------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `onboardingUuid`                   | string          | The record's ID, the last part of the setup link                                                                                                                                                                                                       |
| `parentUuid`                       | string          | The site                                                                                                                                                                                                                                               |
| `dealId`, `companyId`, `contactId` | integer         | The HubSpot deal, company and contact IDs                                                                                                                                                                                                              |
| `onboardingTs`                     | integer or null | When the setup form was sent for this record, in ms; `null` until then. The setup link works only while it is `null` ([POST /v1/guest/onboarding/{uuid}](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-v1guestonboardinguuid)) |

## User relation result object

One group's result in [POST /v1/admin/user-relations/multiple](#post-v1adminuser-relationsmultiple) (`app/Http/Resources/v1/Admin/CreateMultipleUserRelationsResource.php`, `FailuresUserRelationsResource.php`).

| Field                      | Type    | Meaning                                                                                                                                                                                                          |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `businessUuid`             | string  | The group                                                                                                                                                                                                        |
| `success.count`            | integer | The users added to the group                                                                                                                                                                                     |
| `failures`                 | object  | Only when some rows failed: `count` and `users`                                                                                                                                                                  |
| `failures.users[].message` | string  | "User duplication found!", "User exists and is already part of the business" or "User exists but was previously removed from the business"                                                                       |
| `failures.users[].user`    | object  | For a user who is or was in the group: `fFirstName`, `fLastName`, `fUsername`, `fCountryCode`, `fMobile`, `fAddress`, `uuid_tUserType` and `uuid_tBusiness`. For a duplicate: the row as sent, password included |

## Support hours object

A site's support hours: the `data` of [GET](#get-support-hoursparent_uuid), [POST](#post-support-hoursparent_uuid) and [PUT /support-hours/{parent\_uuid}](#put-support-hoursparent_uuid), and of [DELETE /support-hours/{parent\_uuid}/{log\_uuid}](#delete-support-hoursparent_uuidlog_uuid) (apipy @ 0e83c85e5a, `model/t_parent_support.py:100-216`).

* **The site:** `fName`, `fCustomerType`, `fAddress`, `fPostalCode`, `fCity`, `fCountry`, `origin`, `email_key`, `timezone_name`, `reg_notes` (staff notes on the site) and `fCreatedTs`. The site's UUID is not returned.
* **`support_minutes_detail`:** `deposit` is the sum of the deposits, `withdraw` the sum of the withdrawals, `credit` the minutes of the first credit in `logs`, and `remaining` is `deposit + credit − withdraw`. Entries count whether or not they are approved \[[ASK-203](https://github.com/snapfix/docs/blob/main/ASK.md#ask-203-what-should-approving-support-minutes-mean-and-who-may-approve-or-delete-entries)], and notes do not count.
* **`logs`:** the live entries, most recently changed first (by `fServerTs`, which an approval changes too): `uuid`, `fType` (`0` note, `1` deposit, `2` withdrawal, `3` credit), `fDescription`, `fValueMinutes`, `fApproved`, `fApprovedTs`, `uuid_tUser_ApprovedBy`, `fCreatedTs` and `uuid_tUser_CreatedBy`.
* **Names:** `name_tUser_CreatedBy` is the creator's first and last name, or `null`. `name_tUser_ApprovedBy` is set when an approver is recorded, but it holds the creator's name (`:195`).

```json
{
  "fName": "Riverside Hotel",
  "fCustomerType": "paying_customer",
  "fAddress": "1 Quay Street",
  "fPostalCode": "SW1A 1AA",
  "fCity": "London",
  "fCountry": "GB",
  "origin": "web",
  "email_key": "riverside",
  "timezone_name": "Europe/London",
  "reg_notes": null,
  "fCreatedTs": 1764000000000,
  "support_minutes_detail": { "deposit": 600, "withdraw": 120, "credit": 60, "remaining": 540 },
  "logs": [
    { "uuid": "log-1", "fType": 1, "fDescription": "Monthly support hours", "fValueMinutes": 600, "fApproved": 1, "fApprovedTs": 1794300000000, "uuid_tUser_ApprovedBy": "201", "fCreatedTs": 1794200000000, "uuid_tUser_CreatedBy": "200", "name_tUser_CreatedBy": "Jane Smith", "name_tUser_ApprovedBy": "Jane Smith" }
  ]
}
```

## Marketing popup object

A marketing popup campaign: a whole [`mkt_popup`](https://docs.snapfix.com/engineering-reference/db/tables/mkt_popup.md) row, as [admin\_create\_mkt\_popup](#post-actionadmin_create_mkt_popup), [admin\_mkt\_popup\_detail](#post-actionadmin_mkt_popup_detail), [admin\_modify\_mkt\_popup](#post-actionadmin_modify_mkt_popup) and [admin\_delete\_mkt\_popup](#post-actionadmin_delete_mkt_popup) return it. [admin\_list\_mkt\_popup](#post-actionadmin_list_mkt_popup) returns some of the fields.

| Field                                                                                     | Type                             | Meaning                                                                                                                                                      |
| ----------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`, `uuid`                                                                              | integer, string                  | The row's IDs                                                                                                                                                |
| `name`                                                                                    | string                           | The campaign's name                                                                                                                                          |
| `parent_uuid_json`                                                                        | array of strings, string or null | The sites it is shown to; `null`, or the text `null`, means every site. A list after create and in the detail; the stored JSON text after a change or delete |
| `parents_json`                                                                            | array                            | The detail only: the `uuid` and `fName` of each of those sites                                                                                               |
| `ios_disable`, `android_disable`, `web_disable`                                           | integer                          | `1` hides the popup on that platform                                                                                                                         |
| `image_portrait_url`, `image_landscape_url`                                               | string or null                   | The images; at least one is set                                                                                                                              |
| `campaign_url`, `locale_bcp47`, `timezone_iana`                                           | string or null                   | The link it opens, its language tag, and the time zone of the day windows                                                                                    |
| `campaignStartTs`, `campaignEndTs`                                                        | integer or null                  | When the campaign runs, in ms                                                                                                                                |
| `mon_startAfterMidnightMs` … `sun_durationMs`                                             | integer or null                  | For each weekday, when the popup starts showing after midnight and for how long, in ms                                                                       |
| `fActive`, `fDeleted`                                                                     | integer                          | `1` while it is active; `1` once it is deleted                                                                                                               |
| `fCreatedTs`, `fModifiedTs`, `fServerTs`, `uuid_tUser_CreatedBy`, `uuid_tUser_ModifiedBy` | integer, string                  | Row times and the token users who created and last changed it                                                                                                |

The apps get the live, active popups of their site through [`get_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-actionget_mkt_popup).

## Guestline site object (php-apis)

A site's Guestline settings and its Guestline admin, as [admin\_read\_gl\_parent](#post-actionadmin_read_gl_parent) and [admin\_modify\_gl\_parent](#post-actionadmin_modify_gl_parent) return them, from the site's newest [`guestline_parent`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_parent.md) row (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:23476-23514`). The Guestline password is never returned.

| Field                                            | Type    | Meaning                                                                                                                         |
| ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tUser_Admin`                               | string  | The site's Guestline admin user                                                                                                 |
| `fEnabled`                                       | integer | `1` while the Guestline link is on                                                                                              |
| `gl_siteid`, `gl_interfaceid`, `gl_operatorcode` | string  | Guestline's site ID, interface ID and operator code                                                                             |
| `fDeleted`, `fCreatedTs`, `fModifiedTs`          | integer | Row state and times, in ms                                                                                                      |
| `user_admin`                                     | object  | The admin's `uuid`, `fFirstName`, `fLastName`, `fUsername`, `fImage`, `fCountryCode`, `fMobile`, `fCreatedTs` and `fModifiedTs` |

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "uuid_tUser_Admin": "200",
    "fEnabled": 1,
    "gl_siteid": "G-100",
    "gl_interfaceid": "1",
    "gl_operatorcode": "OP1",
    "fDeleted": 0,
    "fCreatedTs": 1794300000000,
    "fModifiedTs": 1794300000000,
    "user_admin": { "uuid": "200", "fFirstName": "Jane", "fLastName": "Smith", "fUsername": "jane@example.com", "fImage": null, "fCountryCode": "44", "fMobile": "7700900123", "fCreatedTs": 1794300000000, "fModifiedTs": 1794300000000 }
  }
}
```

## Sales package object

A package of the admin sales bundle with its prices, as [admin\_read\_stripe\_products\_v3](#post-actionadmin_read_stripe_products_v3) lists it (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/stripe.functions.php:1364-1403`).

| Field                                              | Type                    | Meaning                                                                                                                                                        |
| -------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `package_uuid`, `package_name`, `created_at`       | string, string, integer | The [`package_server`](https://docs.snapfix.com/engineering-reference/db/tables/package_server.md) row's ID, name and creation time                            |
| `fStartTs`, `fEndTs`, `subscription_start_date_ts` | integer or null         | The package's dates, in ms                                                                                                                                     |
| `days_past_permitted`, `days_future_permitted`     | integer                 | How many days into the past or the future a subscription may start                                                                                             |
| `card_eft`                                         | string                  | The payment types, comma-separated, such as `card,sepa_debit`                                                                                                  |
| `package_url`                                      | string                  | The package's page, on the live package site in live mode and the test site otherwise                                                                          |
| `parents`                                          | object                  | `initiated`, `active` and `inactive`: always `0`, since nothing fills them                                                                                     |
| `price_items`                                      | array                   | The live prices: `uuid`, `name`, `mandatory`, `recurring`, `currency`, `amount` (in the smallest unit), `qty_editable`, `qty_default`, `qty_min` and `qty_max` |

## Paywall package object

A paywall package with its schema and prices, as [snapfix\_packages](#post-actionsnapfix_packages), [create\_snapfix\_package](#post-actioncreate_snapfix_package) and [update\_package\_schema](#post-actionupdate_package_schema) return it (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/paypack.functions.schema-v1.php:38-107`).

| Field                                      | Type             | Meaning                                                                                                                                                                                                                                                               |
| ------------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `type`, `name`, `description`      | string           | The [`package_server`](https://docs.snapfix.com/engineering-reference/db/tables/package_server.md) row's ID, type (`core` or `supplement`), name and description                                                                                                      |
| `package`                                  | object           | The paywall schema: the package's limits and switches, such as `paywall_version` and `permission`                                                                                                                                                                     |
| `package_in_use`                           | integer          | `1` when any [`package_server_parent`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_parent.md) row names the package, whatever its state; else `0`                                                                                         |
| `currency_supported`, `interval_supported` | array of strings | The currencies and intervals of its prices                                                                                                                                                                                                                            |
| `price`                                    | array            | Its [`package_server_pricing`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_pricing.md) rows: `uuid` (the Stripe product of that price, for packages made here), `description`, `amount`, `currency`, `interval` and `uuid_package_server` |

## Looker metric object

The answer of every `looker_*` action. It has `status`, not `result` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/looker.functions.php`).

| Field                            | Type           | Meaning                                                                                                                           |
| -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `status`, `message`              | string         | `success` and "Successfully fetched the metrics.", or `error` and the error's text                                                |
| `data.title`, `data.description` | string         | The metric's name and description                                                                                                 |
| `data.chartType`                 | string         | `Line Chart`, `Combined Line Chart` or `Table`                                                                                    |
| `data.timePeriod`                | object         | `startDate` and `endDate` of the window, `Y-m-d`, or `Y-m` for the churn rate                                                     |
| `data.metrics`                   | array          | For the metrics over all sites: one row per week, or per month for the churn rate. Each section lists its row fields              |
| `data.customers`                 | array          | For the per-site metrics: per site, `accountName` (`uuid`, `fName`, `fCustomerType`, `fImage`) and its `metrics`                  |
| `appliedFilter`                  | object or null | The `filter` sent, echoed back                                                                                                    |
| `availableFilter`                | object         | Unless `fetchAvailableFilterValues` is `false`: the values the filter can take, in `ages`, `countries`, `industries` and `types`  |
| `serverTs`, `request_serial`     | integer        | Added by the dispatcher, and removed again when the request was logged in the IP log (`html/api/snapfix/web/index.php:2543-2571`) |

```json
{
  "status": "success",
  "message": "Successfully fetched the metrics.",
  "data": {
    "title": "Weekly Active Users Report",
    "description": "Report showing the active users over the last 8 weeks filtered by various criteria.",
    "chartType": "Line Chart",
    "timePeriod": { "startDate": "2026-09-14", "endDate": "2026-11-08" },
    "metrics": [ { "xHint": "2026-09-14 to 2026-09-20", "xHintV2": "Week of Sep 14, 2026 (Week 38 of 2026)", "xValue": 1, "yHint": "Active Users", "yValue": 42 } ]
  },
  "appliedFilter": { "types": ["paying_customer"] },
  "availableFilter": { "ages": ["<60 days", ">60 days", "All time"], "countries": ["GB"], "industries": ["Hospitality"], "types": ["paying_customer", "churn"] }
}
```


---

# 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/staff.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.
