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

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

Groups (called businesses in the code and the apps): listing and reading a site's groups, creating, copying, changing and deleting them, their member lists and new-activity counts, and the bulk loads and syncs the mobile apps use to keep groups on the device.

A group is a row of [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) with `enum_BusinessType` `task`, in one site (`uuid_tParent`). Asset registers use the same tables with the type `asset` and are in [Assets](https://docs.snapfix.com/engineering-reference/api/assets.md). Not here: a group's tags and tag folders ([Tags](https://docs.snapfix.com/engineering-reference/api/tags.md)), its QR forms ([QR](https://docs.snapfix.com/engineering-reference/api/qr.md)), adding and removing members ([Users](https://docs.snapfix.com/engineering-reference/api/users.md)), and making a group from a template with `?action=webcust_clone_template` ([Onboarding](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actionwebcust_clone_template)).

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`; `apipy` at `https://z2.snapfix.com`
* **Auth:** api\_php\_live\_v2: user token (authpy access JWT in `Authorization: Bearer`). Each endpoint then checks the caller's relation to the group or site, as its section says. The rule for changing and deleting a group passes every active member, and the member list and archive count accept any multi-site user. 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)]; with it off, the shared Basic login). The actions that name a user take it from the body, not the token. Only `group_taskcount` checks the caller's membership; the others check nothing about the group or site. apipy: user token (authpy JWT in `Authorization: Bearer`) on all five routes. They check no staff flag and no site or group rights, and the two that write take the acting user from the request.
* **Used by:** web\_app\_v2 (Fix groups list, create and duplicate dialogs, group settings, task, chat, planner and report pages), iOS and Android (group data loads, sync, create and duplicate forms, task counts), webadmin\_angular (the staff groups page), snapfix\_ai\_agent (Simon's group and member lookups); 35 of the 60 endpoints have no known caller
* **Errors:** the envelope and the codes every `/v1/app` route can return are in [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); the php-apis and apipy envelopes are in [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses). Each endpoint lists its own.
* **Logs:** Laravel calls go to the request log, with the response when it is under about 100 KB; php-apis calls go to its daily request log, with the response when it is under about 100 KB.

| Method | Path                                                                                                               | Service            | Purpose                                                                           |
| ------ | ------------------------------------------------------------------------------------------------------------------ | ------------------ | --------------------------------------------------------------------------------- |
| GET    | [`/v1/app/businesses`](#get-v1appbusinesses)                                                                       | api\_php\_live\_v2 | List a site's groups                                                              |
| POST   | [`/v1/app/businesses`](#post-v1appbusinesses)                                                                      | api\_php\_live\_v2 | Create a group from a template                                                    |
| POST   | [`/v1/app/businesses/copy`](#post-v1appbusinessescopy)                                                             | api\_php\_live\_v2 | Copy a group within its site                                                      |
| POST   | [`/v1/app/businesses/get-updates`](#post-v1appbusinessesget-updates)                                               | api\_php\_live\_v2 | Count new task activity per group                                                 |
| GET    | [`/v1/app/businesses/mark-as-visited/{businessUuid}`](#get-v1appbusinessesmark-as-visitedbusinessuuid)             | api\_php\_live\_v2 | Mark a group as visited                                                           |
| POST   | [`/v1/app/businesses/multi`](#post-v1appbusinessesmulti)                                                           | api\_php\_live\_v2 | Get the caller's groups by UUID                                                   |
| GET    | `/v1/app/businesses/{businessUuid}/job-count`                                                                      | api\_php\_live\_v2 | Count a group's tasks (no caller)                                                 |
| GET    | [`/v1/app/businesses/{businessUuid}/job-count-to-archived`](#get-v1appbusinessesbusinessuuidjob-count-to-archived) | api\_php\_live\_v2 | Count a group's tasks to archive                                                  |
| GET    | [`/v1/app/businesses/{uuid}`](#get-v1appbusinessesuuid)                                                            | api\_php\_live\_v2 | Get a group                                                                       |
| PUT    | [`/v1/app/businesses/{uuid}`](#put-v1appbusinessesuuid)                                                            | api\_php\_live\_v2 | Change a group and its settings                                                   |
| DELETE | [`/v1/app/businesses/{uuid}`](#delete-v1appbusinessesuuid)                                                         | api\_php\_live\_v2 | Delete a group                                                                    |
| GET    | [`/v1/app/businesses/{uuid}/users`](#get-v1appbusinessesuuidusers)                                                 | api\_php\_live\_v2 | List a group's members                                                            |
| GET    | `/v1/app/multiSites/{uuid}/list/businesses`                                                                        | api\_php\_live\_v2 | List a multi-site's groups (no caller)                                            |
| GET    | [`/v1/app/parents/list/businesses`](#get-v1appparentslistbusinesses)                                               | api\_php\_live\_v2 | List the caller's groups across sites (`ParentController@businesses`)             |
| POST   | [`?action=check_duplicate_business`](#post-actioncheck_duplicate_business)                                         | php-apis           | Check whether a group name is taken in a site                                     |
| ANY    | `?action=create_pri_business`                                                                                      | php-apis           | Create groups, generic table action (no caller)                                   |
| ANY    | `?action=create_pri_settings_business`                                                                             | php-apis           | Create group settings, generic table action (no caller)                           |
| ANY    | `?action=create_pri_status`                                                                                        | php-apis           | Create statuses, generic table action (no caller)                                 |
| ANY    | `?action=create_pri_status_sub`                                                                                    | php-apis           | Create sub-statuses, generic table action (no caller)                             |
| ANY    | `?action=create_pub_settings_default`                                                                              | php-apis           | Create default settings, generic table action (no caller)                         |
| ANY    | `?action=delete_pri_business`                                                                                      | php-apis           | Delete groups, generic table action (no caller)                                   |
| ANY    | `?action=delete_pri_settings_business`                                                                             | php-apis           | Delete group settings, generic table action (no caller)                           |
| ANY    | `?action=delete_pri_status`                                                                                        | php-apis           | Delete statuses, generic table action (no caller)                                 |
| ANY    | `?action=delete_pri_status_sub`                                                                                    | php-apis           | Delete sub-statuses, generic table action (no caller)                             |
| ANY    | `?action=delete_pub_settings_default`                                                                              | php-apis           | Delete default settings, generic table action (no caller)                         |
| POST   | [`?action=duplicate_business`](#post-actionduplicate_business)                                                     | php-apis           | Copy a group into a site (`cloneBusiness`)                                        |
| POST   | [`?action=group_taskcount`](#post-actiongroup_taskcount)                                                           | php-apis           | Count a group's tasks by colour                                                   |
| POST   | [`?action=modify_pri_business`](#post-actionmodify_pri_business)                                                   | php-apis           | Change or delete groups by UUID, generic table action that also logs to the queue |
| ANY    | `?action=modify_pri_settings_business`                                                                             | php-apis           | Change group settings, generic table action (no caller)                           |
| ANY    | `?action=modify_pri_status`                                                                                        | php-apis           | Change statuses, generic table action (no caller)                                 |
| ANY    | `?action=modify_pri_status_sub`                                                                                    | php-apis           | Change sub-statuses, generic table action (no caller)                             |
| ANY    | `?action=modify_pub_settings_default`                                                                              | php-apis           | Change default settings, generic table action (no caller)                         |
| POST   | [`?action=read_business_data`](#post-actionread_business_data)                                                     | php-apis           | Read all of a group's data                                                        |
| ANY    | `?action=read_data_business`                                                                                       | php-apis           | Read all data of several groups (no caller)                                       |
| POST   | [`?action=read_parent_business_data_v2`](#post-actionread_parent_business_data_v2)                                 | php-apis           | Read the master data of a user's groups in some sites (v2)                        |
| ANY    | `?action=read_pri_business`                                                                                        | php-apis           | Read groups by UUID, generic table action (no caller)                             |
| ANY    | `?action=read_pri_settings_business`                                                                               | php-apis           | Read group settings by UUID, generic table action (no caller)                     |
| ANY    | `?action=read_pri_status`                                                                                          | php-apis           | Read statuses by UUID, generic table action (no caller)                           |
| ANY    | `?action=read_pri_status_sub`                                                                                      | php-apis           | Read sub-statuses by UUID, generic table action (no caller)                       |
| ANY    | `?action=read_pub_settings_default`                                                                                | php-apis           | Read default settings by UUID, generic table action (no caller)                   |
| ANY    | `?action=read_pub_status`                                                                                          | php-apis           | Read default statuses by UUID, generic table action (no caller)                   |
| ANY    | `?action=read_pub_status_sub`                                                                                      | php-apis           | Read default sub-statuses by UUID, generic table action (no caller)               |
| ANY    | `?action=save_new_business`                                                                                        | php-apis           | Create a group (`saveNewBusiness`) (no caller)                                    |
| POST   | [`?action=save_pri_business`](#post-actionsave_pri_business)                                                       | php-apis           | Save groups (the apps' sync)                                                      |
| POST   | [`?action=save_pri_settings_business`](#post-actionsave_pri_settings_business)                                     | php-apis           | Save group settings (the apps' sync)                                              |
| POST   | [`?action=save_pri_status`](#post-actionsave_pri_status)                                                           | php-apis           | Save statuses (the apps' sync)                                                    |
| POST   | [`?action=save_pri_status_sub`](#post-actionsave_pri_status_sub)                                                   | php-apis           | Save sub-statuses (the apps' sync)                                                |
| ANY    | `?action=save_pub_settings_default`                                                                                | php-apis           | Save default settings, generic table action (no caller)                           |
| ANY    | `?action=save_pub_status`                                                                                          | php-apis           | Save default statuses, generic table action (no caller)                           |
| ANY    | `?action=save_pub_status_sub`                                                                                      | php-apis           | Save default sub-statuses, generic table action (no caller)                       |
| ANY    | `?action=webcust_business_delete`                                                                                  | php-apis web       | Delete a group (no caller)                                                        |
| ANY    | `?action=webcust_business_details`                                                                                 | php-apis web       | Get a group's details (no caller)                                                 |
| ANY    | `?action=webcust_business_list`                                                                                    | php-apis web       | List a site's groups (no caller)                                                  |
| ANY    | `?action=webcust_business_update`                                                                                  | php-apis web       | Change a group's details (no caller)                                              |
| ANY    | `?action=webcust_list_business`                                                                                    | php-apis web       | List groups (no caller)                                                           |
| POST   | [`/copy-group-data`](#post-copy-group-data)                                                                        | apipy              | Copy a group's members, schedules and settings into other groups                  |
| POST   | [`/group`](#post-group)                                                                                            | apipy              | Create a group                                                                    |
| GET    | `/group/{uuid}`                                                                                                    | apipy              | Get a group (no caller)                                                           |
| POST   | `/groups`                                                                                                          | apipy              | Create groups (no caller)                                                         |
| GET    | [`/v4/groups/{parentUUID}`](#get-v4groupsparentuuid)                                                               | apipy              | List a site's groups with their members                                           |

Notes on the table:

* Rows marked "(no caller)" have no call site in any client repo. Some of the php-apis actions appear in the apps' endpoint registries (iOS `ApiEndpointManager.swift`, Android `APIEndPointUtils.java`), which are not calls. `GET /v1/app/multiSites/{uuid}/list/businesses` and `GET /v1/app/businesses/{businessUuid}/job-count` appear in no client at all. Whether any of them are still needed is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* `GET /v1/app/multiSites/{uuid}/list/businesses` would return the task groups of every site of a multi-site, with their sites, to any user with a membership row of the multi-site, removed ones included.
* The web calls only the Laravel routes. The apps use php-apis for their group data, task counts and sync, and the staff admin app uses `modify_pri_business` and the apipy routes.
* Every php-apis action with a caller is sent as `POST` with a JSON body (ios @ aa31967ac8, `APIManagers/APIManager.swift:933`, `:1399`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/ApiUtils.java:72`, `app/src/main/java/gmail/com/snapfixapp/network/ApiService.java:101`).

## GET /v1/app/businesses

Lists the groups of one site that the caller can see, with paging, search, sorting and task counts.

* **Auth:** user token. The route checks only that the site exists, so any signed-in user may call it for any site. The list holds the caller's own groups, and a non-member gets an empty list. A multi-site user of the site who sends `source=multisite` gets every group of the site, except a group whose newest membership row is the user's own removed one (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/AssetBusinessService.php:67-71`, `app/Models/BusinessModel.php:326-340`).
* **Used by:** web\_app\_v2 (`GroupHttpService.getGroupList`: the Fix groups list and feed, the group pickers and filters, the planner, the reports, and the housekeeping task and staff dialogs), snapfix\_ai\_agent (`BusinessesApi.list_businesses`, Simon's group lookup and site check).

**Request** (query string)

| Name            | In    | Type                            | Required | Rules                                                                                                                                                                                                                           |
| --------------- | ----- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent`        | query | string                          | yes      | A site that exists in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md). Missing or unknown: `422`                                                                                       |
| `source`        | query | `site` or `multisite`           | no       | Default `site`: the caller's own groups. `multisite`: see Auth. Other values: `422`                                                                                                                                             |
| `archived`      | query | `0` or `1`                      | no       | `1` lists the inactive groups (`fInActive` 1), `0` the active ones; without it, both. The web's group list sends it for its archived filter                                                                                     |
| `search`        | query | string                          | no       | A text match on the group's name and address joined by a space. No length limit; the value is bound into a `LIKE`. A group with no address never matches                                                                        |
| `sortBy`        | query | `name`, `created` or `modified` | no       | Sorts by `fName`, `fCreatedTs` or `fModifiedTs`; other values: `422`. Every list is then ordered by the group's latest change (its own, or the newest chat in its tasks), newest first; without `sortBy` that is the only order |
| `orderBy`       | query | `asc` or `desc`, any case       | no       | Default `desc`; used only with `sortBy`. Other values: `422`                                                                                                                                                                    |
| `limit`         | query | integer                         | no       | Page size. With it, the answer has `pagination`; without it, every group comes back                                                                                                                                             |
| `offset`        | query | integer                         | no       | Page number from 1, used with `limit`. Default 1                                                                                                                                                                                |
| `withJobsCount` | query | `0` or `1`                      | no       | Default `1`: each group gets `statuses` with task counts, which loads every task of the listed groups. `0` leaves `statuses` out                                                                                                |

**Response** `200`: `data.businesses` is a list of [group objects](#group-object), each with `parent`, `settings` and, with `withJobsCount`, `statuses`. `createPermission` is the caller's "create group" right in the site (`fCreateNewBusiness` on their row in [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md)). `totalCount` counts the groups the caller can see in the site, and `filterCount` the same after the `archived` filter; neither applies `search`. `pagination` comes with `limit`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "businesses": [
      {
        "uuid": "group-200",
        "name": "Maintenance",
        "image": null,
        "address": "Room 101",
        "inActive": 0,
        "purpose": null,
        "instructions": null,
        "notificationDisabled": 0,
        "parent": { "uuid": "site-1", "name": "Main site", "image": null },
        "statuses": {
          "red": { "uuid": "status-1", "name": "red", "count": 3, "definition": "New tasks" },
          "amber": { "uuid": "status-2", "name": "amber", "count": 1, "definition": "Tasks in progress" },
          "green": { "uuid": "status-3", "name": "green", "count": 9, "definition": "Completed tasks" }
        },
        "settings": { "relationUuid": "relation-1", "role": "Admin", "onboard": "Active", "autoArchiveEnabled": 0 }
      }
    ],
    "createPermission": true,
    "totalCount": 12,
    "filterCount": 12,
    "pagination": { "total": 12, "perPage": 25, "currentPage": 1, "lastPage": 1, "from": 1, "to": 12 }
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` for a missing or unknown `parent`, or a `source`, `sortBy`, `orderBy` or `archived` outside its list.

**Side effects:** none.

## POST /v1/app/businesses

Creates a group in a site from a built-in template, and makes the caller its admin.

* **Auth:** user token. The caller needs the site's "create group" right (`fCreateNewBusiness` on their row in [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md)); without it, or without a row in the site, `403` "Access denied".
* **Used by:** web\_app\_v2 (`GroupHttpService.createGroup`, the "Create a new Group" dialog of the Fix groups list).

**Request** (JSON or form)

| Name            | In   | Type   | Required | Rules                                                                                                                                                                                                                                |
| --------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parent_uuid`   | body | string | yes      | The site. Not checked to exist: a site the caller isn't in gives `403`                                                                                                                                                               |
| `name`          | body | string | yes      | Unique among the site's task groups that aren't deleted. A taken name: `422` "The name has already been taken."                                                                                                                      |
| `template_uuid` | body | string | no       | One of the built-in templates (the `Template` enum); other values: `422`. Default: the blank template. A listed template that is missing from the database gives `404`                                                               |
| `address`       | body | string | no       | Checked to be a string, then not used: the group takes the template's address (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/BusinessController.php:230`, `app/Services/AssetBusinessService.php:216`) |

**Response** `200`: message "Business created successfully"; `data` is a [group object](#group-object) with `parent`, `statuses`, `settings`, `users` (the caller, as `Admin`) and `invited`. `tagHeaders` is not included.

```json
{
  "status": "success",
  "message": "Business created successfully",
  "data": {
    "uuid": "group-201",
    "name": "Housekeeping",
    "image": null,
    "address": "Room 101",
    "inActive": 0,
    "purpose": null,
    "instructions": null,
    "notificationDisabled": null,
    "parent": { "uuid": "site-1", "name": "Main site", "image": null },
    "statuses": { "red": { "uuid": "status-4", "name": "red", "count": 2, "definition": "New tasks" } },
    "settings": { "relationUuid": "relation-2", "role": "Admin", "onboard": "Active" },
    "users": [ { "uuid": "user-100", "name": "Jane Smith", "role": "Admin", "onboard": "Active" } ],
    "invited": []
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `404` for a missing template; `422` for a missing or taken `name` or an unknown `template_uuid`.

**Side effects:**

* Inserts the group in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) with the template's other fields. Its purpose and instructions start empty, and its colour definitions take the defaults.
* Copies the template's settings ([`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md)), statuses ([`tPri_Status`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_status.md)), sub-statuses ([`tPri_StatusSub`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_statussub.md)), and tasks with their checklists ([`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md)). The template's tags and chats are not copied.
* Adds the caller as an active Admin in [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md).
* Adds 1 to the site's `group_count` ([Firebase counters](#common-side-effects)).

## POST /v1/app/businesses/copy

Copies a group into the same site under a new name, with its settings, statuses, tasks and, by default, their chat. The caller becomes the copy's admin.

* **Auth:** user token. The caller needs the "create group" right in the source group's site, but doesn't need to be a member of the source group, so they can copy a group whose tasks and chats they can't see. The copy always goes into the source's site.
* **Used by:** web\_app\_v2 (`GroupHttpService.createDuplicateGroup`, the duplicate dialog of the Fix groups list, which always sends `copyJobChat`).

**Request** (JSON)

| Name                 | In   | Type    | Required | Rules                                                                         |
| -------------------- | ---- | ------- | -------- | ----------------------------------------------------------------------------- |
| `sourceBusinessUuid` | body | string  | yes      | A group that isn't deleted. Otherwise `422`                                   |
| `name`               | body | string  | yes      | Unique among the site's task groups that aren't deleted. Otherwise `422`      |
| `copyJobChat`        | body | boolean | no       | Default `true`: also copy the tasks' chat messages, reactions and status logs |

**Response** `200`: as [POST /v1/app/businesses](#post-v1appbusinesses), for the copy.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the right in the source's site; `422` for an unknown or deleted source, or a taken name.

**Side effects:**

* Inserts the copy with the source's other fields, such as its address, image and inactive flag. Its purpose, instructions and colour definitions start from the defaults.
* Copies the settings, statuses and sub-statuses, and every task of the source that isn't archived and whose task time (`fJobTs`) has come, with their checklists and task tags ([`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md)). Each copied task gets the caller as a follower ([`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md)).
* Tag folders are linked, not copied: the copy gets rules in [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md) for the source's folders. The source's own folders move to the site (`uuid_tParent` set, `uuid_tBusiness` cleared), and the source gets rules for them too (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/TagHeaderService.php:142-160`).
* With `copyJobChat`, copies the copied tasks' chat messages ([`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md)), reactions ([`tPri_JobChat_Reaction`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat_reaction.md)) and status logs ([`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md)).
* Adds the caller as an active Admin of the copy, and 1 to the site's `group_count` ([Firebase counters](#common-side-effects)).

## POST /v1/app/businesses/get-updates

For each group in the request that the caller is in, counts the tasks with new activity since the caller last visited the group. The web shows the counts on the group list.

* **Auth:** user token. Groups the caller isn't in are left out of the answer, but they still get visit rows (see side effects).
* **Used by:** web\_app\_v2 (`GroupHttpService.getGroupListUpdates`, after the Fix groups list loads a page).

**Request** (JSON)

| Name            | In   | Type             | Required | Rules                                                                           |
| --------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------- |
| `businessUuids` | body | array of strings | yes      | The groups to check. Missing, not a list, or an item that isn't a string: `422` |

**Response** `200`: `data` has one entry per group in the request that the caller is a member of. `updatedJobCount` counts the group's tasks that aren't archived, are created by now, and whose chat changed (`fJobChatModifiedTs`) after the caller's last visit. Admins and members with "view all tasks" count every task; other members count the tasks they created, follow or are assigned to.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [{ "businessUuid": "group-200", "updatedJobCount": 3 }]
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` as above.

**Side effects:** for each UUID in the request with no visit row for the caller yet, adds one to [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md) with the current time, also for groups the caller isn't in and for UUIDs that don't exist. That row then counts as the last visit.

## GET /v1/app/businesses/mark-as-visited/{businessUuid}

Records that the caller has seen a group's tasks, which clears the group's new-activity count.

* **Auth:** user token. There is no membership check: a row is written for any UUID.
* **Used by:** web\_app\_v2 (`TaskHttpService.markTaskListAsVisited`, when the caller leaves a group's task list, or an asset register's asset list, that had updates).

**Request**

| Name           | In   | Type   | Required | Rules     |
| -------------- | ---- | ------ | -------- | --------- |
| `businessUuid` | path | string | yes      | The group |

**Response** `200`: `{ "status": "success", "message": "Operation was successful", "data": null }`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors).

**Side effects:** adds a row to [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md) for the caller and the group on every call ([viewed rows](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)).

## POST /v1/app/businesses/multi

Returns the groups with the given UUIDs that the caller belongs to, in any site. The web uses it to name the groups behind group chats.

* **Auth:** user token. Only the caller's live memberships of live groups in live sites count. Asset registers come back too.
* **Used by:** web\_app\_v2 (`GroupHttpService.getMultiGroupDetails`, from `ChatDataService`).

**Request** (JSON)

| Name    | In   | Type             | Required | Rules                                    |
| ------- | ---- | ---------------- | -------- | ---------------------------------------- |
| `uuids` | body | array of strings | yes      | The groups. Missing or not a list: `422` |

**Response** `200`: `data.businesses` is a list of [group objects](#group-object), each with `parent`. There is no paging.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` as above.

**Side effects:** none.

## GET /v1/app/businesses/{businessUuid}/job-count-to-archived

Counts the group's green tasks that an auto-archive period of `week` weeks would archive now: green, not archived, and green since at least `week` weeks.

* **Auth:** user token. The caller must be a member of the group, or a multi-site user of any site: the check doesn't pass the group's site. Otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`GroupHttpService.getGroupTaskCountForArchiving`, the auto-archive dialog in group settings).

**Request**

| Name           | In    | Type    | Required | Rules                                                                                     |
| -------------- | ----- | ------- | -------- | ----------------------------------------------------------------------------------------- |
| `businessUuid` | path  | string  | yes      | The group. Not looked up: an unknown UUID gives `403`, or `count` 0 for a multi-site user |
| `week`         | query | integer | yes      | Weeks. Missing or not an integer: `422`. `0` counts every green task                      |

**Response** `200`: `{ "status": "success", "message": "Operation was successful", "data": { "count": 4 } }`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `422` as above.

**Side effects:** none.

## GET /v1/app/businesses/{uuid}

Returns one group with its site, statuses with task counts, settings, members, pending invitations and tag folders.

* **Auth:** user token. The caller must be a member of the group, or a multi-site user of the group's site. Otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`GroupHttpService.getGroupDetails`: group settings, the group details dialog, the selected group of the group list, the task and chat pages, the chat info panel, and the planner's permission check).

**Request**

| Name                 | In    | Type       | Required | Rules                                                                                               |
| -------------------- | ----- | ---------- | -------- | --------------------------------------------------------------------------------------------------- |
| `uuid`               | path  | string     | yes      | The group. Unknown, or an asset register's UUID: `404` "Resource not found"                         |
| `withUsers`          | query | `0` or `1` | no       | Checked, but `users` always comes back                                                              |
| `withTags`           | query | `0` or `1` | no       | Default `1`: include `tagHeaders`                                                                   |
| `withAttributeRules` | query | `0` or `1` | no       | Checked, then not used: the request rule is shared with asset registers, which have attribute rules |

Any other value of the three flags: `422`.

**Response** `200`: `data` is a [group object](#group-object) with `parent`, `statuses`, `settings`, `users`, `invited` and, unless `withTags` is `0`, `tagHeaders`. Every member's contact fields, and every invitee's email address and phone number, go to every member \[[ASK-72](https://github.com/snapfix/docs/blob/main/ASK.md#ask-72-should-every-member-get-the-other-members-and-invitees-contact-details)].

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `404` as above; `422` for a flag outside `0` and `1`.

**Side effects:** none.

## PUT /v1/app/businesses/{uuid}

Changes a group's name, address, purpose, colour definitions, image and settings. The web sends it as a multipart `POST` with `_method=PUT` in the query ([API conventions](https://docs.snapfix.com/engineering-reference/api.md#requests)).

* **Auth:** user token. The policy passes group admins, members with "view business settings" (`perBusSettingsScreenAccess`), and every member who isn't read-only (whose onboarding isn't Inactive). So an ordinary member can change the group, whatever the settings screens show; a read-only member is refused. A caller who isn't a member gets `403` with the text `messages.access_denied`.
* **Used by:** web\_app\_v2 (`GroupHttpService.updateGroup`: Save on the group settings page, and the settings drawer, whose "Archive this group" is sent as `inActive`).

**Request** (multipart or JSON)

| Name                                                                                                    | In   | Type       | Required | Rules                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------- | ---- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                                                                  | path | string     | yes      | The group                                                                                                                                                      |
| `name`                                                                                                  | body | string     | yes      | Unique among the site's other task groups that aren't deleted; the group's own name passes                                                                     |
| `address`                                                                                               | body | string     | yes      |                                                                                                                                                                |
| `inActive`                                                                                              | body | boolean    | no       | `1` archives (deactivates) the group, `0` restores it. Kept when missing                                                                                       |
| `purpose`, `instructions`                                                                               | body | string     | no       | Nullable. A request without them clears them                                                                                                                   |
| `redDefinition`, `amberDefinition`, `greenDefinition`                                                   | body | string     | no       | Nullable. What each colour means in this group. A request without them clears them                                                                             |
| `tagsRequired`                                                                                          | body | string     | no       | JSON text: a list of `{ "uuid", "mandatory" }`, one per tag folder, for the folders a new task must use                                                        |
| `tag1Required`, `tag2Required`, `tag3Required`                                                          | body | boolean    | no       | Three tag rules, stored but not in the response                                                                                                                |
| `roomRequired`, `assetRequired`, `assigneeRequired`                                                     | body | boolean    | no       | What a new task must have                                                                                                                                      |
| `taskApprovalRequired`                                                                                  | body | boolean    | no       | Green tasks need approval. `0` approves the waiting ones (see side effects)                                                                                    |
| `blockGreenWhenChecklistNotComplete`, `autoYellowWhenChecklistStart`, `autoGreenWhenChecklistCompleted` | body | boolean    | no       | Checklist rules                                                                                                                                                |
| `autoArchiveEnabled`                                                                                    | body | boolean    | no       | Auto-archive. `1` also archives the green tasks older than the interval (see side effects)                                                                     |
| `autoArchivePeriodEnum`                                                                                 | body | `week`     | no       | Nullable; `week` is the only period                                                                                                                            |
| `autoArchiveInterval`                                                                                   | body | integer    | no       | Weeks, nullable. With `autoArchiveEnabled` 1, an interval of `0` archives every green task, and a missing one makes the call fail after the group row is saved |
| `areaAssociatedTask`, `areaOrRoomAssociatedTask`                                                        | body | integer    | no       | Nullable. How tasks link to areas and rooms                                                                                                                    |
| `jobToDoNfcAllowManualOverride`, `dailyGroupEmailAndReport`, `blockGalleryPhoto`                        | body | boolean    | no       | Other settings                                                                                                                                                 |
| `file`                                                                                                  | body | image file | no       | The group's image: a type from the `ImageType` list, up to `FILE_MAX_SIZE`                                                                                     |

**Response** `200`: message "Business updated successfully"; `data` is a [group object](#group-object) with `parent`, `statuses`, `settings`, `invited` and `tagHeaders`, without `users`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` (see Auth); `404` "Resource not found" for an unknown group; `422` for the first failed rule, such as a taken name, a missing address or a file that isn't an allowed image.

**Side effects:**

* Updates [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) (name, address, inactive flag, image, and the purpose, instructions and colour definitions in `fGuideJson`) and [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md). A change of `autoArchiveEnabled` records the caller in `uuid_tUser_fAutoArchive_ModifiedBy`.
* With `tagsRequired`, creates or updates the group's rules in [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md).
* Every request with `autoArchiveEnabled` 1, not only one that turns it on, queues `AutoArchiveJobs`: each green task that turned green longer ago than the interval is archived, with a line in its chat.
* With `taskApprovalRequired` 0, queues `ApprovalRequiredJobs`: each green task waiting for approval is approved, with a line in its chat.

## DELETE /v1/app/businesses/{uuid}

Deletes a group by marking it deleted.

* **Auth:** user token, with the same policy as [PUT /v1/app/businesses/{uuid}](#put-v1appbusinessesuuid). A non-member gets the text `messages.access_denied`.
* **Used by:** web\_app\_v2 (`GroupHttpService.deleteGroup`, "Delete This Group" in group settings, after a confirmation).

**Request**

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

**Response** `200`: `{ "status": "success", "message": "Business deleted successfully", "data": null }`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` (see Auth); `404` "Resource not found".

**Side effects:**

* Sets `fDeleted` to 1 on the group in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md). Its tasks, members and settings are not changed \[[ASK-80](https://github.com/snapfix/docs/blob/main/ASK.md#ask-80-what-should-deleting-a-group-do-to-its-tasks-and-members)].
* Takes 1 off the site's `group_count` ([Firebase counters](#common-side-effects)).

## GET /v1/app/businesses/{uuid}/users

Lists a group's members with their role, state and permissions in it.

* **Auth:** user token. The caller must be a member of the group, or a multi-site user of any site: the check doesn't pass the group's site. Otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`UserHttpService.getGroupUserList`: the task users dialog, the reminder dialogs, the user filter and chat; group settings gets its members from [GET /v1/app/businesses/{uuid}](#get-v1appbusinessesuuid) instead), snapfix\_ai\_agent (`BusinessesApi.users`, Simon's people, name-resolving and task tools).

**Request**

| Name   | In   | Type   | Required | Rules                                                  |
| ------ | ---- | ------ | -------- | ------------------------------------------------------ |
| `uuid` | path | string | yes      | The group. Unknown, or an asset register's UUID: `404` |

**Response** `200`: `data` is a list of [member objects](#member-object), one per live membership. Every member's contact fields go to every member \[[ASK-72](https://github.com/snapfix/docs/blob/main/ASK.md#ask-72-should-every-member-get-the-other-members-and-invitees-contact-details)].

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "user-100",
      "isSystem": false,
      "relationUuid": "relation-1",
      "name": "Jane Smith",
      "firstname": "Jane",
      "lastname": "Smith",
      "address": "Room 101",
      "staffUsername": null,
      "image": null,
      "username": "jane@example.com",
      "countryCode": 44,
      "mobile": 7700900123,
      "relationDeleted": 0,
      "active": 1,
      "role": "Admin",
      "user_type": "admin",
      "onboard": "Active",
      "notificationDisabled": 0,
      "tempUser": 0,
      "permissions": { "perJobViewAll": 1, "perJobCreateNew": 1 }
    }
  ]
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `404` as above.

**Side effects:** none.

## GET /v1/app/parents/list/businesses

Lists the groups the caller belongs to across all their sites, or in one site when `parentUuid` is sent \[[ASK-117](https://github.com/snapfix/docs/blob/main/ASK.md#ask-117-should-site-reports-on-one-site-list-only-that-sites-groups)].

* **Auth:** user token. Only the caller's live memberships of live groups in live sites count. Asset registers come back too.
* **Used by:** web\_app\_v2 (`GroupHttpService.getGroupListByAccounts`: the groups-by-account filter and the account admin reports).

**Request** (query string)

| Name         | In    | Type   | Required | Rules                                                                                       |
| ------------ | ----- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `parentUuid` | query | string | no       | Only the groups of this site. Read without validation; an unknown value gives an empty list |

**Response** `200`: `data.businesses` is a list of [group objects](#group-object), each with `parent`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors).

**Side effects:** none.

## POST ?action=check\_duplicate\_business

Says whether a group name is already used in a site, and by an active, inactive or deleted group. The apps ask before they create, rename or copy a group or asset register.

* **Auth:** user token, 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)]. There is no membership check, so any signed-in user can probe any site's group names.
* **Used by:** iOS (`CreateFirstGroupGuideVC`, `BusinessListingVC`, `BusinessDetailsVC`, `DuplicatePopupVC`, `AddAssetGroupVC`), Android (`CreateGroupActivity`, `ManageGroupActivity`, `DuplicateGroupBottomSheet`, `CreateAssetGroupActivity`).

**Request** (JSON)

| Name                       | In   | Type              | Required | Rules                                        |
| -------------------------- | ---- | ----------------- | -------- | -------------------------------------------- |
| `uuid_tParent_destination` | body | string            | yes      | The site                                     |
| `new_business_name`        | body | string            | yes      | Compared without case, as sent               |
| `enum_BusinessType`        | body | `task` or `asset` | no       | Default `task`; other values count as `task` |

**Response** `200`: `result` is always `true`. The apps read `message`, which names the state of the groups with that name (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:15073-15149`):

| Message                                            | When                                                            |
| -------------------------------------------------- | --------------------------------------------------------------- |
| "No existing group"                                | No group of the type in the site has the name                   |
| "Active group with the same name already exists"   | An active group has the name                                    |
| "Inactive group with the same name already exists" | One group has the name, and it is inactive                      |
| "InActive group with the same name already exists" | Several groups have the name, none active, one or more inactive |
| "Deleted group with the same name already exists"  | Only deleted groups have the name                               |

```json
{ "result": true, "message": "Active group with the same name already exists", "serverTs": 1794387600000 }
```

**Errors:** `200` with `result: false` and "uuid\_tParent\_destination, new\_business\_name must be mentioned in the request!", naming the fields that are missing or blank. An empty body: `{ "success": "0", "message": "Data cannot be blank!" }`.

**Side effects:** none.

## POST ?action=duplicate\_business

Copies a group into a site and makes a named user its admin. It is the apps' "Duplicate group"; the web uses [POST /v1/app/businesses/copy](#post-v1appbusinessescopy). It runs the same copy (`cloneBusiness`) as [`webcust_clone_template`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actionwebcust_clone_template).

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The action checks only that the user, the site and the source group exist. It doesn't check that the caller is in the source group or the site, or that the named user is the caller, and the copy brings the source's tasks and its assignees' memberships along. Whether a copy should keep the source's members is open \[[ASK-73](https://github.com/snapfix/docs/blob/main/ASK.md#ask-73-should-copying-a-group-copy-its-members)].
* **Used by:** iOS (`DuplicatePopupVC`), Android (`DuplicateGroupBottomSheet`). Both send the source's own site and the signed-in user.

**Request** (JSON)

| Name                       | In   | Type              | Required | Rules                                                                                                                                                           |
| -------------------------- | ---- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tBusiness_source`    | body | string            | yes      | The group to copy. Deleted groups are found too                                                                                                                 |
| `uuid_tParent_destination` | body | string            | yes      | The site for the copy                                                                                                                                           |
| `uuid_tUser_destination`   | body | string            | yes      | The user who becomes the copy's creator and Admin                                                                                                               |
| `new_business_name`        | body | string            | no       | The copy's name. Default: the source's name. Not checked for duplicates; the apps call [check\_duplicate\_business](#post-actioncheck_duplicate_business) first |
| `enum_BusinessType`        | body | `task` or `asset` | no       | Default `task`. `asset` sets the copy's address to its name, the asset colour definitions and the default asset attributes                                      |
| `copy_job_chat`            | body | boolean           | no       | Default: copy the source's chats. `false`: each copied task gets one "Snapfix Created The Task" chat line instead. Both apps send it                            |

**Response** `200`: `result: true`, `message` "Values Found", and `data`, a [group master data object](#group-master-data-object) of the copy with `tPri_Business`, `tPri_User`, `tPri_UserBusiness`, `tPri_SettingsBusiness`, `tPri_Status`, `tPri_StatusSub`, `tPri_TagHeader`, `tPri_Tag`, `tPri_Job`, `tPri_JobChat`, `tPri_JobTag`, `tPri_JobTodo` and `tPri_JobUser`.

**Errors:** `200` with `result: false`: "invalid parameters" (a required field is missing or blank), "invalid user", "invalid parent", "invalid business", "invalid business settings" (the source has no settings row). An empty body: `{ "success": "0", "message": "Data cannot be blank!" }`.

**Side effects** (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:12569-13198`):

* Inserts the copy in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) with the source's other columns, and copies its settings ([`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md)), statuses ([`tPri_Status`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_status.md)), sub-statuses ([`tPri_StatusSub`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_statussub.md)) and checklist permissions ([`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md), [`tPri_CL_SiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatepermissions.md)).
* Tag folders: adds rules in [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md) that link the source's own folders to the source and to the copy, then copies the source's rules to the copy. The step meant to move those folders to the site does nothing.
* Adds `uuid_tUser_destination` as an active Admin in [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md).
* Copies the source's tasks that aren't archived or deleted and whose task time has come into [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), dated now, with their rooms ([`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md)), areas ([`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md)) and reminders ([`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md)). The new admin follows each copy ([`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md)).
* Copies the task tags ([`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md)), the checklist items ([`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md)) and, unless `copy_job_chat` is `false`, the chats with their reactions, all of the whole source group, deleted chats included. The rows of tasks it didn't copy are stored with no task.
* Copies the live assignments ([`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md)). An assignee who isn't in the copy yet gets their source membership, with its role and permissions, copied into the copy.
* Adds to the site's `group_count`, `user_count` (once, for the admin) and `task_count` (one per task) ([Firebase counters](#common-side-effects)). With the queue settings on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)], logs each row to the queue and asks apipy to push "API update required" to the copy's members.

## POST ?action=group\_taskcount

Counts a group's tasks by colour, as the caller sees them: every task for admins and members with "view all tasks" (`perJobViewAll`), otherwise the tasks the caller created, follows or is assigned to.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The caller is the token's user, not a body field, and must have a live membership of the group.
* **Used by:** iOS (`HomeVC`, the task counts of a group's task list; `ChatGroupInfoVC`), Android (`TaskViewModel`, the task list; `GroupChatInfoActivity`). The calls in the iOS group and asset register context menus are commented out.

**Request** (JSON)

| Name            | In   | Type   | Required | Rules                      |
| --------------- | ---- | ------ | -------- | -------------------------- |
| `business_uuid` | body | string | yes      | A group that isn't deleted |

**Response** `200`: `result: true`, `message` "success", and the counts in `data`. Tasks stored as `yellow` count as amber.

| Field                                                                   | Meaning                                                                                                          |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `red`, `amber`, `green`                                                 | Tasks of that colour that aren't archived or deleted, have a status and are created by now; frozen ones included |
| `red_archived`, `amber_archived`, `green_archived`                      | Archived tasks of that colour                                                                                    |
| `red_frozen`, `amber_frozen`, `green_frozen`                            | Frozen tasks that aren't archived. Counted for app version 6.10.38 or later; otherwise 0                         |
| `red_frozen_archived`, `amber_frozen_archived`, `green_frozen_archived` | Frozen archived tasks, with the same version rule                                                                |

```json
{
  "result": true,
  "message": "success",
  "data": {
    "red": 3, "amber": 1, "green": 7,
    "red_archived": 0, "amber_archived": 0, "green_archived": 2,
    "red_frozen": 0, "amber_frozen": 0, "green_frozen": 0,
    "red_frozen_archived": 0, "amber_frozen_archived": 0, "green_frozen_archived": 0
  },
  "serverTs": 1794387600000
}
```

**Errors:** `200` with `result: false`: "invalid params" (no `business_uuid`), "invalid access!" (no user in the token), "invalid business!" (unknown or deleted), "invalid user role" (the caller isn't a member), "no jobs found!" (a member without "view all tasks" who has no task of their own). An empty body: "Data cannot be blank!".

**Side effects:** none.

## POST ?action=modify\_pri\_business

Changes group rows by UUID. The staff admin app uses it to rename a group, change its address, make it inactive or delete it.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The action checks nothing about the caller: not membership, not admin, not staff. Any signed-in user can change or delete any group by its UUID.
* **Used by:** webadmin\_angular (`GroupService.modifyGroup`, the group dialog of the groups page, including its delete).

**Request** (JSON)

| Name          | In   | Type             | Required | Rules                                                                                                                                                                                                                                                                                                                              |
| ------------- | ---- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update_data` | body | array of objects | yes      | Each object has the group's `uuid` and the columns to set, any column of [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md). The admin app sends the whole row with new `fName`, `fAddress`, `fInActive` and `fDeleted`. A base64 `fImage` is stored as a file and replaced with its URL |

**Response** `200`: `result: true`, `message` "Record has been updated successfully.", and `data` with the rows as they are after the update. When some UUIDs aren't found, `message` is "Some of the records failed to update. You can find the updated records here!" and `result` is still `true`.

```json
{
  "result": true,
  "message": "Record has been updated successfully.",
  "data": [{ "id": 123, "uuid": "group-200", "fName": "Maintenance", "fAddress": "Room 101", "fInActive": 0, "fDeleted": 0 }],
  "serverTs": 1794387600000
}
```

**Errors:** `200` with `result: false`, "Record failed to update." and an `err_code` when no row was updated. An empty body: `{ "success": "0", "message": "Data cannot be blank!" }`.

**Side effects:** updates the [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) rows and sets their `fServerTs`; with the queue settings on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)], logs each change to the queue. It doesn't change the groups' members, tasks or settings.

## POST ?action=read\_business\_data

Returns all of one group's data, table by table, for the apps' local database.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The action takes only the group's UUID and checks neither the token's user nor membership, so any signed-in user who knows a group's UUID can read the whole group. The user rows carry every column.
* **Used by:** iOS (`APIManager.downloadDataForBusiness` and `downloadParentDataForBusiness`: a new group, a "new group" push, and groups missing from the device), Android (`BusinessDataTaskManager`, the group data loads).

**Request** (JSON)

| Name             | In   | Type   | Required | Rules                                                                                                                             |
| ---------------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tBusiness` | body | string | yes      | The group. Missing: "Invalid Request Params". Deleted groups are read too                                                         |
| `table_data`     | body | array  | no       | Items `{ "table": "tPri_Job", "last_updated_ts": 0 }`, replacing the default list. A table name goes into the SQL without a check |

The default list has 18 tables, all from `0`: `tPri_Status`, `tPri_StatusSub`, `tPri_NotificationBusiness`, `tPri_User`, `tPri_Business`, `tPri_UserBusiness`, `tPri_SettingsBusiness`, `tPri_TagHeader`, `tPri_Tag`, `tPri_Job`, `tPri_JobTag`, `tPri_JobUser`, `tPri_JobChat`, `tPri_JobTodo`, `tPri_JobTodo_Notes`, `tPri_JobNotif`, `tPri_ParentJobAttributeRule` and `tPri_BusinessJobAttributeRule`. Each table returns its rows of the group changed after `last_updated_ts`; `0` returns every row. `tPri_User` holds the users of every membership row of the group, removed members included.

**Response** `200`: `result: true`, `message` "Values Found", and `data`, a [group master data object](#group-master-data-object).

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Business": [{ "uuid": "group-200", "fName": "Maintenance", "uuid_tParent": "site-1", "fDeleted": 0 }],
    "tPri_Job": [{ "uuid": "task-300", "uuid_tBusiness": "group-200", "color": "red", "fTitle": "Leaking tap" }]
  },
  "serverTs": 1794387600000
}
```

**Errors:** `200` with `result: false`: "invalid business" (no group has the UUID), "Invalid Request Params", "No Values Found" (no table has rows).

**Side effects:** none. The read uses the read-only database. The whole group comes back in one answer, with no paging.

## POST ?action=read\_parent\_business\_data\_v2

Returns the master data of a user's groups in the given sites: the groups with their statuses, settings, tags, memberships and users. The apps use it at sign-in and when they switch sites. The answer is gzip-compressed when the client asks for it.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The user comes from `user_uuid` in the body, not the token, so any signed-in user can read another user's groups. The sites and groups aren't checked against the caller. The user rows carry every column.
* **Used by:** iOS (`DownloadDataVC`, the sign-in data load; `BusinessListing+ParentSwither`, the site switch), Android (`DownloadDataActivity`, the sign-in data load, gzip; `BusinessViewModel`).

**Request** (JSON)

| Name           | In   | Type             | Required | Rules                                                                                                                                                                     |
| -------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`    | body | string           | yes      | A user who isn't deleted: "invalid user!"                                                                                                                                 |
| `parent_uuids` | body | array of strings | yes      | A non-empty list ("invalid parent uuids") of sites that all exist, deleted ones included ("invalid parent!" when none is found, "invalid parent count!" when some aren't) |

The groups are those of the user's membership rows in those sites, removed memberships included, in groups that aren't deleted. The code also means to add every group of the sites of the user's multi-sites, but it looks the multi-site's sites up by the wrong column, so it adds them only if a link row's own UUID equals the multi-site's. For app version 6105 or older, only task groups come back. Newer apps also get every asset register of the sites, whether or not the user is in it.

**Response** `200`: `result: true`, `message` "Values Found", and `data`, a [group master data object](#group-master-data-object) with `tPri_Status` (the first three of each group), `tPri_StatusSub`, `tPri_Business` (each with `recent_job_chat_ts`, the time of the group's newest chat), `tPri_SettingsBusiness`, `tPri_TagHeader`, `tPri_Tag`, `tPri_UserBusiness` (every membership row of those groups, removed ones included), `tPri_UserParent`, `tPri_ParentJobAttributeRule`, `tPri_BusinessJobAttributeRule` and `tPri_User`. `tPri_User` holds the members of those groups and every live user of the sites, with every column.

**Errors:** `200` with `result: false`: "user\_uuid must be mentioned in the request!", the messages above, "user is not part of any business!" (no membership row in a live group of those sites) \[[ASK-38](https://github.com/snapfix/docs/blob/main/ASK.md#ask-38-should-a-user-whose-sites-have-no-groups-be-signed-out)], "No Data found!". An empty body: "Data cannot be blank!".

**Side effects:** none. Everything comes back in one answer, with no paging.

## POST ?action=save\_pri\_business

Saves group rows that the apps changed on the device: each row is inserted, or updated when its `uuid` exists.

* **Auth:** user token, 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)]. There is no membership, role or site check, and the user named in a row is only recorded. New groups don't need the site's "create group" right.
* **Used by:** iOS (`TaskManager`, the sync of changed and new groups), Android (`SyncRepository`, the same).

**Request** (JSON)

| Name          | In   | Type             | Required | Rules                                                                                                                                                                                                                                        |
| ------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md), handled as the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis) describes |

Android also sends `business_settings_data`, which the server doesn't read. A row with both `uuid_tParent` and `fName` goes through a duplicate-name check that is inverted: a row whose name is free in its site is counted as failed, and a row whose name an active or inactive group already has is not. The count is all it changes: every row is saved, renames included (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:783-830`, `:1061`). This applies while `LEGACY_QUEUE_SUPPORT` is off; with it on, the rows go to the queue instead \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis); `result` is `false` when any row failed.

```json
{
  "result": true,
  "message": "Please find the processed record count",
  "total_record_count": 1,
  "inserted_record_count": 0,
  "updated_record_count": 1,
  "insert_failed_record_count": 0,
  "update_failed_record_count": 0,
  "trigger_auto_archive": [],
  "serverTs": 1794387600000
}
```

**Errors:** as in the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Side effects:** inserts or updates [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) rows. After the response, runs the queue processor (`processLogQueue`), which does nothing unless a queue setting is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST ?action=save\_pri\_settings\_business

Saves group settings rows that the apps changed on the device.

* **Auth:** as [save\_pri\_business](#post-actionsave_pri_business): no membership or role check.
* **Used by:** iOS (`TaskManager`), Android (`SyncRepository`), the sync of changed settings.

**Request** (JSON)

| Name          | In   | Type             | Required | Rules                                                                                                                |
| ------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md) |

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis). `trigger_auto_archive` lists the saved rows with `fAutoArchiveEnabled` 1 and a `uuid`.

**Errors:** as in the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Side effects:** inserts or updates [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md) rows. After the response, for each row in `trigger_auto_archive`, archives the group's green tasks older than its interval, when the stored row has auto-archive on, a period and an interval above 0. This runs on every such save, not only when auto-archive is turned on: the check for a change from off reads the stored row wrongly.

## POST ?action=save\_pri\_status

Saves a group's status rows (its red, amber and green statuses) that the apps changed on the device.

* **Auth:** as [save\_pri\_business](#post-actionsave_pri_business).
* **Used by:** iOS (`TaskManager`), Android (`SyncRepository`).

**Request** (JSON)

| Name          | In   | Type             | Required | Rules                                                                                                                                                                   |
| ------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_Status`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_status.md): `uuid`, `uuid_tBusiness`, `fName`, `fSortOrder` and the other columns |

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** as in the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Side effects:** inserts or updates [`tPri_Status`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_status.md) rows, then runs the queue processor, as [save\_pri\_business](#post-actionsave_pri_business) does.

## POST ?action=save\_pri\_status\_sub

Saves a group's sub-status rows that the apps changed on the device.

No screen shows or edits sub-statuses, and the web has no code for them. iOS and Android create the defaults "New", "In Progress" and "Closed" on the device for a new group, and stamp "New" on new and copied tasks (ios @ aa31967ac8, `SnapFix/BusinessTagsEditVC.swift:216-217`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/CreateGroupActivity.java:539-546`, `:648`, `app/src/main/java/gmail/com/snapfixapp/fragment/JobChatFragment.java:7352`).

* **Auth:** as [save\_pri\_business](#post-actionsave_pri_business).
* **Used by:** iOS (`TaskManager`), Android (`SyncRepository`).

**Request** (JSON)

| Name          | In   | Type             | Required | Rules                                                                                                  |
| ------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_StatusSub`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_statussub.md) |

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** as in the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Side effects:** inserts or updates [`tPri_StatusSub`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_statussub.md) rows, then runs the queue processor, as [save\_pri\_business](#post-actionsave_pri_business) does.

## POST /copy-group-data

Copies the members, schedules (planned tasks) and settings of one group into other groups. The staff admin app uses it to set a group up from another.

* **Auth:** user token (`@jwt_required`). The route checks no staff flag and no rights on either group, and `user_uuid` isn't compared with the token's user, so any signed-in user can copy members, admins included, into any group in any site.
* **Used by:** webadmin\_angular (`GroupService.copyGroupDetails`, the copy group details dialog of the groups page).

**Request** (JSON)

| Name                      | In   | Type             | Required         | Rules                                                                                                                                                                                                                                                                                                                                              |
| ------------------------- | ---- | ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_business_uuid`    | body | string           | yes              | The group to copy from                                                                                                                                                                                                                                                                                                                             |
| `user_uuid`               | body | string           | yes              | Recorded as the creator of the new rows; not checked                                                                                                                                                                                                                                                                                               |
| `destination_businesses`  | body | array of objects | yes              | At least one. Each has `uuid` (the group) and one way to find its admin: `admin_user_uuid`; otherwise `consider_any_admin_uuid` `1` for the destination's newest admin; otherwise `consider_admin_from_source` `1`, with `copy_users`, for the source's newest admin. No admin found: "invalid destination group admin", before anything is copied |
| `copy_users`              | body | boolean          | one of the three | `true`: copy the source's live members who aren't in the destination yet, with their roles and permissions                                                                                                                                                                                                                                         |
| `copy_schedules`          | body | boolean          | one of the three | `true`: copy the source's live schedules into each destination. The destination's admin becomes a member there if they aren't one                                                                                                                                                                                                                  |
| `copy_all_group_settings` | body | boolean          | one of the three | `true`: copy the settings row, the tag folders (reusing a destination folder with the same name) and the tags the destination doesn't have. Statuses and sub-statuses are not copied                                                                                                                                                               |

The three flags must be JSON `true`; a `1` doesn't count.

**Response** `200`: `data` is a list with one object per destination, keyed by its UUID. `copiedConfigurationStatus` and `copiedConfigurationStatusSub` are always 0.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": [
    {
      "group-201": {
        "copiedUserCount": 3,
        "copiedScheduleCount": 2,
        "copiedConfigurationSettingsBusiness": 1,
        "copiedConfigurationStatus": 0,
        "copiedConfigurationStatusSub": 0,
        "copiedConfigurationTagHeader": 3,
        "copiedConfigurationTag": 9
      }
    }
  ]
}
```

**Errors:** `200` with `result: false`: "invalid params" (no `source_business_uuid`, `user_uuid` or destination), "invalid destination group admin", "invalid operation to perform" (none of the three flags is `true`).

**Side effects:**

* `copy_users`: inserts [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows in each destination, and adds 1 to the destination site's `user_count` for each ([Firebase counters](#common-side-effects)).
* `copy_schedules`: inserts the source's schedules that aren't deleted and have a next run into [`schedule`](https://docs.snapfix.com/engineering-reference/db/tables/schedule.md) and [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md), pointed at the destination and its admin's membership. An admin membership it adds also counts in `user_count`.
* `copy_all_group_settings`: inserts a second settings row in [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md), and rows in [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md) and [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md).

## POST /group

Creates a group in a site, with default settings, statuses (Red, Amber, Green), sub-statuses (New, In Progress, Closed), tag folders and tags. The staff admin app's group dialog uses it.

* **Auth:** user token (`@jwt_required`). The route checks no staff flag and no rights in the site, so any signed-in user can create a group in any site. The creator is the form's `user_uuid`, not the token's user. Values from `user_uuid`, `business_uuid` and the optional settings fields go into the SQL text.
* **Used by:** webadmin\_angular (`GroupService.saveGroup`, the group dialog of the groups page).

**Request** (form data)

| Name                                                                                                                                          | In   | Type   | Required | Rules                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuid`                                                                                                                                 | body | string | yes      | A site that exists and isn't deleted: "invalid parent!"                                                                                                                                                                                                                     |
| `fName`                                                                                                                                       | body | string | yes      | A live group of the site with the same name and address: "group already exists!". The same name with another address passes                                                                                                                                                 |
| `fAddress`                                                                                                                                    | body | string | yes      |                                                                                                                                                                                                                                                                             |
| `user_uuid`                                                                                                                                   | body | string | no       | The creator. Default: the text `admin`, which the admin app always gets, since it doesn't send one \[[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)] |
| `business_uuid`                                                                                                                               | body | string | no       | The new group's UUID. Default: a new one                                                                                                                                                                                                                                    |
| `fImage`, `fGuideJson`, `fContact`, `fPhone`, `fEmail`, `fCustomerType`, `fWebsite`, `sort_order`, `fOrigin`                                  | body | string | no       | Stored on the group                                                                                                                                                                                                                                                         |
| `fAutoLogout`, `fForceUpdate`, `fPromptUpdate`, `fDefRedDotAlert`, `fJobToDoListLimit`, `fJobUserLimit`, `fJobTagBucketLimit`, `fTagRequired` | body | string | no       | Stored in the group's settings                                                                                                                                                                                                                                              |

**Response** `200`: `data` holds the new group's rows: `business`, `settings`, `status`, `sub_status`, `tag_header` and `tag`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": {
    "business": { "uuid": "group-202", "uuid_tParent": "site-1", "fName": "Maintenance", "fAddress": "Room 101" },
    "settings": { "uuid_tBusiness": "group-202", "fDeleted": 0 },
    "status": [{ "fName": "Red", "fSortOrder": 1 }],
    "sub_status": [{ "fName": "New", "fSortOrder": 1 }],
    "tag_header": [{ "fName": "Location" }],
    "tag": [{ "fName": "Room 1" }]
  }
}
```

**Errors:** `200` with `result: false`: "invalid params" (`fName`, `fAddress` or `parent_uuid` missing), "invalid parent!", "group already exists!".

**Side effects:** inserts the rows in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md), [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md), [`tPri_Status`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_status.md), [`tPri_StatusSub`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_statussub.md), [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md) and [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md), and adds 1 to the site's `group_count` ([Firebase counters](#common-side-effects)). It adds no member: nobody, not even the creator, is in the new group.

## GET /v4/groups/{parentUUID}

Lists every live group of a site, with each group's members and their usernames and phone numbers. The staff admin app's copy group details dialog uses it to pick the source and destination groups.

* **Auth:** user token (`@jwt_required`). The route checks no staff flag and no membership, so any signed-in user can list any site's groups and members.
* **Used by:** webadmin\_angular (`GroupService.getGroupsWithUsers`, the copy group details dialog).

**Request**

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

**Response** `200`: `data.items` has one object per group that isn't deleted, asset registers included, newest first, with no paging. `users` lists the group's live members. Each group's list is built with one `GROUP_CONCAT`, which the database may cut short, and a member with any of the seven fields empty is left out.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": {
    "items": [
      {
        "group_uuid": "group-200",
        "group_name": "Maintenance",
        "users": [
          { "uuid": "user-100", "fUsername": "jane@example.com", "fCountryCode": "44", "fMobile": "7700900123", "fFirstName": "Jane", "fLastName": "Smith", "fName": "Jane Smith" }
        ]
      }
    ]
  }
}
```

**Errors:** `200` with `result: false` and "record(s) not found" when the site has no live groups.

**Side effects:** none.

## Group object

A group as the Laravel endpoints return it (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/AssetBusinessResource.php:18-38`). The blocks after `notificationDisabled` appear only where the endpoint's section names them.

| Field                     | Type            | Meaning                                                                                                                                                                                                                                                                                                                                              |
| ------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                    | string          | The group                                                                                                                                                                                                                                                                                                                                            |
| `name`, `address`         | string          | The group's name and address                                                                                                                                                                                                                                                                                                                         |
| `image`                   | string or null  | The group's image URL                                                                                                                                                                                                                                                                                                                                |
| `inActive`                | integer         | `1` when the group is archived (inactive)                                                                                                                                                                                                                                                                                                            |
| `purpose`, `instructions` | string or null  | The group's purpose and instructions. Filled only by [GET /v1/app/businesses/{uuid}](#get-v1appbusinessesuuid); `null` elsewhere                                                                                                                                                                                                                     |
| `notificationDisabled`    | integer or null | `1` when the caller has muted the group. Filled by the lists and the single-group read                                                                                                                                                                                                                                                               |
| `parent`                  | object          | The site's `uuid`, `name` and `image`                                                                                                                                                                                                                                                                                                                |
| `statuses`                | object          | Keyed `red`, `amber` and `green` (a stored `Yellow` reads as `amber`). Each has `uuid`, `name`, `count`, the group's tasks of that colour that aren't archived and that the caller can see ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)), and `definition`, what the colour means in this group |
| `settings`                | object          | A [group settings object](#group-settings-object)                                                                                                                                                                                                                                                                                                    |
| `users`                   | array           | [Member objects](#member-object), one per live membership \[[ASK-72](https://github.com/snapfix/docs/blob/main/ASK.md#ask-72-should-every-member-get-the-other-members-and-invitees-contact-details)]                                                                                                                                                |
| `invited`                 | array           | Pending invitations: `uuid`, `countryCode`, `mobile`, `username`, `invitedEmail` and `invitedSms` \[[ASK-72](https://github.com/snapfix/docs/blob/main/ASK.md#ask-72-should-every-member-get-the-other-members-and-invitees-contact-details)]                                                                                                        |
| `tagHeaders`              | array           | The tag folders the group owns or links by a rule, with their tags and rules                                                                                                                                                                                                                                                                         |

## Group settings object

The `settings` of a [group object](#group-object) (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/SettingsBusinessResource.php:15-52`). The fields after `blockGalleryPhoto` are for task groups only.

| Field                                                                                                   | Type                     | Meaning                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `relationUuid`, `role`, `onboard`, `permissions`                                                        |                          | The caller's membership: its UUID, the role (`Admin` or `User`), the onboarding state and the permissions, as in the [member object](#member-object). A multi-site user who isn't a member gets the role `User`, onboarding `Inactive` and the multi-site defaults |
| `jobToDoNfcAllowManualOverride`                                                                         | integer                  | NFC checklist items can be ticked by hand                                                                                                                                                                                                                          |
| `blockGalleryPhoto`                                                                                     | integer                  | Task photos must come from the camera, not the gallery                                                                                                                                                                                                             |
| `dailyGroupEmailAndReport`                                                                              | integer                  | The daily group email and report are on                                                                                                                                                                                                                            |
| `assigneeRequired`, `assetRequired`, `roomRequired`                                                     | integer                  | What a new task must have                                                                                                                                                                                                                                          |
| `blockGreenWhenChecklistNotComplete`, `autoYellowWhenChecklistStart`, `autoGreenWhenChecklistCompleted` | integer                  | Checklist rules                                                                                                                                                                                                                                                    |
| `taskApprovalRequired`                                                                                  | integer                  | Green tasks need approval                                                                                                                                                                                                                                          |
| `autoArchiveEnabled`, `autoArchivePeriodEnum`, `autoArchiveInterval`                                    | integer, string, integer | Auto-archive: on or off, the period (`week`) and the number of periods                                                                                                                                                                                             |
| `areaAssociatedTask`, `areaOrRoomAssociatedTask`                                                        | integer                  | How tasks link to areas and rooms                                                                                                                                                                                                                                  |

## Member object

A member of a group, as [GET /v1/app/businesses/{uuid}/users](#get-v1appbusinessesuuidusers) and the `users` of a [group object](#group-object) return it (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/UserAssetBusinessResource.php:19-46`).

| Field                                                   | Type            | Meaning                                                                                                                                                                                                                                       |
| ------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                  | string          | The member's user                                                                                                                                                                                                                             |
| `isSystem`                                              | boolean         | `true` for Snapfix's own system user                                                                                                                                                                                                          |
| `relationUuid`                                          | string          | The membership row in [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md)                                                                                                                    |
| `name`, `firstname`, `lastname`                         | string          | `name` is the first and last name                                                                                                                                                                                                             |
| `address`, `image`, `username`, `countryCode`, `mobile` | string, number  | The user's address, photo, email address and phone number; `countryCode` and `mobile` are numbers \[[ASK-72](https://github.com/snapfix/docs/blob/main/ASK.md#ask-72-should-every-member-get-the-other-members-and-invitees-contact-details)] |
| `staffUsername`                                         | string or null  | The username of a username login                                                                                                                                                                                                              |
| `role`                                                  | string          | `Admin` or `User`                                                                                                                                                                                                                             |
| `user_type`                                             | string          | The user's type in the group's site (`user_type` of their live [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row, such as `admin`), or `normal` when they have none                        |
| `active`, `onboard`                                     | integer, string | The membership's active flag and onboarding state                                                                                                                                                                                             |
| `relationDeleted`                                       | integer         | Always `0`: only live memberships are listed                                                                                                                                                                                                  |
| `notificationDisabled`                                  | integer         | `1` when the member has muted the group                                                                                                                                                                                                       |
| `tempUser`                                              | integer         | `1` for a user with a temporary password who has never signed in, otherwise `0`                                                                                                                                                               |
| `permissions`                                           | object          | The member's group permissions, keyed by column, such as `perJobViewAll` and `perJobCreateNew`                                                                                                                                                |

## Group master data object

The `data` of [read\_business\_data](#post-actionread_business_data), [read\_parent\_business\_data\_v2](#post-actionread_parent_business_data_v2) and [duplicate\_business](#post-actionduplicate_business): one key per table, each a list of rows with every column as stored, as in the [table data object](https://docs.snapfix.com/engineering-reference/api/tasks.md#table-data-object-php-apis). Each section lists its tables; a table with no rows is left out.

## Common side effects

What the endpoints above mean by these words.

* **Firebase counters:** `group_count`, `user_count` and `task_count` under `parentPackageUsage/<site>` in the Firebase Realtime Database. Laravel updates them through its queued Firebase job, php-apis directly, and apipy through php-apis's `fb_parent_subscription`. `group_count` goes up when a group is created, copied or duplicated and down when one is deleted. `user_count` goes up when a copy adds a member: the copy's admin for `duplicate_business`, each added membership for `/copy-group-data`. `task_count` goes up for each task `duplicate_business` copies. The task counter drifts.
* **Change queue:** when `VIA_QUEUE` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)], Laravel's model observers log a sync entry for each group, settings row, status, sub-status, tag folder and membership that is created, changed or deleted. php-apis logs the rows its group actions write when `WEB_QUEUE_SUPPORT` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Viewed rows and the request log:** as in the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).


---

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