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

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

Users and their membership of sites and groups: adding, inviting, blocking and listing users, staff usernames, and on-call lists.

* **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`; `authpy` at `https://z3.snapfix.com`
* **Auth:** api\_php\_live\_v2: user token (authpy JWT in `Authorization: Bearer`). php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]); actions use the `user_uuid` in the request, not the token's user; some actions take HTTP Basic with `AUTH_USERNAME` instead \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. apipy: user token (authpy JWT in `Authorization: Bearer`). authpy: user token (`Authorization: Bearer`); the `/parent-users` routes don't check that the caller belongs to the site.
* **Used by:** web\_app\_v2, iOS, Android, webadmin\_angular, snapfix\_ai\_agent, authpy, apipy; 44 of the 93 endpoints have no known caller
* **Answers:** each service's envelope and status codes are in [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses). api\_php\_live\_v2 translates its messages on the server, so `message` holds English text such as "Operation was successful" (`lang/en/messages.php:267`). authpy answers errors with HTTP `200` and `result: false`.
* **authpy routes** read a JSON body, take the caller from the token (`get_jwt_identity()`) and run the abuse check under the route's name before anything else ([Blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)); `/block-devices-v2` uses the name `block-device-per-parent`, `/block-users` `block-user-per-parent`, and the three `/parent-users` routes share `parent-users`. In every route here, a body that is not JSON ends in a server error, because the error handler reads a variable that was never set (for example authpy @ 5d5758661c, `app.py:2205-2224`).
* **Site admin check (authpy):** most authpy routes here accept only a caller with a live `tPri_UserParent` row of type `admin` for the request's `parentUUID`, or a live multi-site membership whose multi-site covers that site; anyone else gets `unauthorised access`. Sections that accept other callers say so.

| Method | Path                                                                                                         | Service            | Purpose                                                                                                                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/app/parents/add-user`                                                                                   | api\_php\_live\_v2 | Add a user to a site (no caller)                                                                                                                                                                         |
| GET    | [`/v1/app/parents/{uuid}/users`](#get-v1appparentsuuidusers)                                                 | api\_php\_live\_v2 | List a site's users                                                                                                                                                                                      |
| GET    | [`/v1/app/staff-username`](#get-v1appstaff-username)                                                         | api\_php\_live\_v2 | List staff usernames                                                                                                                                                                                     |
| POST   | [`/v1/app/staff-username`](#post-v1appstaff-username)                                                        | api\_php\_live\_v2 | Create a staff username                                                                                                                                                                                  |
| POST   | [`/v1/app/user/add-relation/{item_uuid}`](#post-v1appuseradd-relationitem_uuid)                              | api\_php\_live\_v2 | Add a user to a group or asset (`item_uuid`)                                                                                                                                                             |
| GET    | [`/v1/app/user/get-role`](#get-v1appuserget-role)                                                            | api\_php\_live\_v2 | Get the user's role                                                                                                                                                                                      |
| POST   | `/v1/app/user/invite-to/{item_uuid}`                                                                         | api\_php\_live\_v2 | Invite a user to a group or asset (`item_uuid`) (no caller) \[[ASK-76](https://github.com/snapfix/docs/blob/main/ASK.md#ask-76-should-the-web-send-invitations-or-should-its-unused-invitation-code-go)] |
| POST   | [`/v1/app/user/multi`](#post-v1appusermulti)                                                                 | api\_php\_live\_v2 | Get several users                                                                                                                                                                                        |
| POST   | [`/v1/app/user/on-call`](#post-v1appuseron-call)                                                             | api\_php\_live\_v2 | List on-call users                                                                                                                                                                                       |
| POST   | [`/v1/app/user/start-app`](#post-v1appuserstart-app)                                                         | api\_php\_live\_v2 | Log an app start                                                                                                                                                                                         |
| DELETE | [`/v1/app/user/{invite_id}/invite-cancel/{item_uuid}`](#delete-v1appuserinvite_idinvite-cancelitem_uuid)     | api\_php\_live\_v2 | Cancel an invitation                                                                                                                                                                                     |
| PUT    | [`/v1/app/user/{invite_id}/invite-resend/{item_uuid}`](#put-v1appuserinvite_idinvite-resenditem_uuid)        | api\_php\_live\_v2 | Resend an invitation                                                                                                                                                                                     |
| DELETE | [`/v1/app/user/{user_uuid}/remove-relation/{item_uuid}`](#delete-v1appuseruser_uuidremove-relationitem_uuid) | api\_php\_live\_v2 | Remove a user from a group or asset                                                                                                                                                                      |
| PUT    | [`/v1/app/user/{user_uuid}/update-relation/{item_uuid}`](#put-v1appuseruser_uuidupdate-relationitem_uuid)    | api\_php\_live\_v2 | Change a user's relation to a group or asset                                                                                                                                                             |
| ANY    | `?action=add_user`                                                                                           | php-apis           | Add a user (no caller)                                                                                                                                                                                   |
| ANY    | `?action=create_pri_user`                                                                                    | php-apis           | Create a user (no caller)                                                                                                                                                                                |
| ANY    | `?action=create_pri_user_business`                                                                           | php-apis           | Create group memberships, generic table action (no caller)                                                                                                                                               |
| ANY    | `?action=create_pri_user_type`                                                                               | php-apis           | Create user types, generic table action (no caller)                                                                                                                                                      |
| POST   | [`?action=delete_group_invitation`](#post-actiondelete_group_invitation)                                     | php-apis           | Cancel a group invitation                                                                                                                                                                                |
| ANY    | `?action=delete_pri_user`                                                                                    | php-apis           | Delete users, generic table action (no caller)                                                                                                                                                           |
| ANY    | `?action=delete_pri_user_business`                                                                           | php-apis           | Delete group memberships, generic table action (no caller)                                                                                                                                               |
| ANY    | `?action=delete_pri_user_type`                                                                               | php-apis           | Delete user types, generic table action (no caller)                                                                                                                                                      |
| POST   | [`?action=group_invitation`](#post-actiongroup_invitation)                                                   | php-apis           | Add or invite a user to a group                                                                                                                                                                          |
| POST   | [`?action=list_group_invitation`](#post-actionlist_group_invitation)                                         | php-apis           | List a group's open invitations                                                                                                                                                                          |
| ANY    | `?action=modify_pri_user`                                                                                    | php-apis           | Change a user (`modifyPriUser`) (no caller)                                                                                                                                                              |
| ANY    | `?action=modify_pri_user_business`                                                                           | php-apis           | Change group memberships, generic table action (no caller)                                                                                                                                               |
| ANY    | `?action=modify_pri_user_type`                                                                               | php-apis           | Change user types, generic table action (no caller)                                                                                                                                                      |
| ANY    | `?action=read_business_users`                                                                                | php-apis           | Read a group's users (no caller)                                                                                                                                                                         |
| POST   | [`?action=read_on_call_users`](#post-actionread_on_call_users)                                               | php-apis           | List one site's on-call users                                                                                                                                                                            |
| POST   | [`?action=read_on_call_users_v2`](#post-actionread_on_call_users_v2)                                         | php-apis           | List the on-call users of several sites                                                                                                                                                                  |
| POST   | [`?action=read_pri_user`](#post-actionread_pri_user)                                                         | php-apis           | Find users by email address, mobile number or UUID, generic table action                                                                                                                                 |
| POST   | [`?action=read_pri_user_business`](#post-actionread_pri_user_business)                                       | php-apis           | Read group memberships, generic table action                                                                                                                                                             |
| ANY    | `?action=read_pri_user_type`                                                                                 | php-apis           | Read user types by UUID, generic table action (no caller)                                                                                                                                                |
| ANY    | `?action=read_server_only_device_user_token`                                                                 | php-apis           | Read device tokens by UUID, generic table action (no caller)                                                                                                                                             |
| ANY    | `?action=read_user`                                                                                          | php-apis           | Read a user (no caller)                                                                                                                                                                                  |
| POST   | [`?action=read_users`](#post-actionread_users)                                                               | php-apis           | List the users of a site or a group                                                                                                                                                                      |
| POST   | [`?action=read_users_v2`](#post-actionread_users_v2)                                                         | php-apis           | Read users' full rows by UUID                                                                                                                                                                            |
| POST   | [`?action=resend_group_invitation`](#post-actionresend_group_invitation)                                     | php-apis           | Resend a group invitation                                                                                                                                                                                |
| POST   | [`?action=save_pri_log_startappuser`](#post-actionsave_pri_log_startappuser)                                 | php-apis           | Log an app start                                                                                                                                                                                         |
| POST   | [`?action=save_pri_new_user_v7`](#post-actionsave_pri_new_user_v7)                                           | php-apis           | Create accounts for users made on the device                                                                                                                                                             |
| ANY    | `?action=save_pri_user`                                                                                      | php-apis           | Save a user (no caller)                                                                                                                                                                                  |
| ANY    | `?action=save_pri_user_business`                                                                             | php-apis           | Save group memberships, generic table action (no caller)                                                                                                                                                 |
| POST   | [`?action=save_pri_user_business_v2`](#post-actionsave_pri_user_business_v2)                                 | php-apis           | Save group memberships (v2)                                                                                                                                                                              |
| ANY    | `?action=save_pri_user_type`                                                                                 | php-apis           | Save user types (no caller)                                                                                                                                                                              |
| POST   | [`?action=save_pri_user_v7`](#post-actionsave_pri_user_v7)                                                   | php-apis           | Save a user's profile                                                                                                                                                                                    |
| ANY    | `?action=save_server_only_device_user_token`                                                                 | php-apis           | Save device tokens, generic table action (no caller)                                                                                                                                                     |
| ANY    | `?action=save_user_added_to_business`                                                                        | php-apis           | Save that a user was added to a group, generic table action (no caller)                                                                                                                                  |
| ANY    | `?action=send_invite`                                                                                        | php-apis           | Send a group invitation, optionally with a new password (no caller)                                                                                                                                      |
| ANY    | `?action=send_invite_multiple`                                                                               | php-apis           | Send several invitations (no caller)                                                                                                                                                                     |
| POST   | [`?action=proxy_add_user`](#post-actionproxy_add_user)                                                       | php-apis web       | Add a user to a site, for authpy (`addUserV2Proxy`)                                                                                                                                                      |
| POST   | [`?action=proxy_add_user_v2`](#post-actionproxy_add_user_v2)                                                 | php-apis web       | Add a user to a site, for authpy (`addUserV2ProxyNew`)                                                                                                                                                   |
| ANY    | `?action=proxy_add_userbusiness`                                                                             | php-apis web       | Add a user to a group, for authpy (no caller)                                                                                                                                                            |
| POST   | [`?action=proxy_add_userbusiness_v2`](#post-actionproxy_add_userbusiness_v2)                                 | php-apis web       | Add users to groups (v2), for authpy                                                                                                                                                                     |
| POST   | [`?action=proxy_add_users`](#post-actionproxy_add_users)                                                     | php-apis web       | Add several users to a site, for authpy                                                                                                                                                                  |
| ANY    | `?action=proxy_add_users_batch`                                                                              | php-apis web       | Add users in batches (`addUsersV2ProxyPatchCall`) (no caller)                                                                                                                                            |
| POST   | [`?action=proxy_manage_userbusiness`](#post-actionproxy_manage_userbusiness)                                 | php-apis web       | Change a user's groups, for authpy                                                                                                                                                                       |
| POST   | [`?action=resend_account_invitation`](#post-actionresend_account_invitation)                                 | php-apis web       | Resend a site invitation, for authpy                                                                                                                                                                     |
| POST   | [`?action=revoke_account_invitation`](#post-actionrevoke_account_invitation)                                 | php-apis web       | Revoke a site invitation, for authpy                                                                                                                                                                     |
| ANY    | `?action=webcust_add_user`                                                                                   | php-apis web       | Add a user (no caller)                                                                                                                                                                                   |
| ANY    | `?action=webcust_add_userbusiness`                                                                           | php-apis web       | Add a user to a group (no caller)                                                                                                                                                                        |
| ANY    | `?action=webcust_delete_userbusiness`                                                                        | php-apis web       | Remove a user from a group (no caller)                                                                                                                                                                   |
| ANY    | `?action=webcust_staffusername_add`                                                                          | php-apis web       | Create a staff username (no caller)                                                                                                                                                                      |
| ANY    | `?action=webcust_staffusername_list`                                                                         | php-apis web       | List staff usernames (no caller)                                                                                                                                                                         |
| ANY    | `?action=webcust_update_user_info`                                                                           | php-apis web       | Change a user's details (no caller)                                                                                                                                                                      |
| ANY    | `?action=webcust_update_userbusiness`                                                                        | php-apis web       | Change a group membership (no caller)                                                                                                                                                                    |
| ANY    | `?action=webcust_user_info`                                                                                  | php-apis web       | Get a user's details (no caller)                                                                                                                                                                         |
| ANY    | `?action=webcust_user_types`                                                                                 | php-apis web       | List user types (no caller)                                                                                                                                                                              |
| ANY    | `?action=webcust_userparent_add`                                                                             | php-apis web       | Add a user to a site (no caller)                                                                                                                                                                         |
| ANY    | `?action=webcust_userparent_save`                                                                            | php-apis web       | Save a site user (no caller)                                                                                                                                                                             |
| POST   | `/group_invite`                                                                                              | apipy              | Send a group invitation (no caller)                                                                                                                                                                      |
| PUT    | `/group_invite`                                                                                              | apipy              | Send a group invitation again, through php-apis `resend_group_invitation` (`groupInvite`) (no caller)                                                                                                    |
| DELETE | `/group_invite`                                                                                              | apipy              | Delete a group invitation, through php-apis `delete_group_invitation` (no caller)                                                                                                                        |
| GET    | `/group_invite/{group_uuid}`                                                                                 | apipy              | List a group's pending invitations (no caller)                                                                                                                                                           |
| POST   | `/add-user`                                                                                                  | authpy             | Add a user (`addUserProfile`) (no caller)                                                                                                                                                                |
| POST   | `/add-user-groups`                                                                                           | authpy             | Add a user to groups (no caller)                                                                                                                                                                         |
| POST   | [`/add-user-groups-v2`](#post-add-user-groups-v2)                                                            | authpy             | Add a user to groups (v2)                                                                                                                                                                                |
| POST   | [`/add-user-v2`](#post-add-user-v2)                                                                          | authpy             | Add a user (v2)                                                                                                                                                                                          |
| POST   | [`/add-users`](#post-add-users)                                                                              | authpy             | Add several users                                                                                                                                                                                        |
| POST   | `/block-devices`                                                                                             | authpy             | Block a user's devices (no caller)                                                                                                                                                                       |
| POST   | [`/block-devices-v2`](#post-block-devices-v2)                                                                | authpy             | Block a user's devices (v2)                                                                                                                                                                              |
| POST   | [`/block-users`](#post-block-users)                                                                          | authpy             | Block users                                                                                                                                                                                              |
| POST   | [`/manage-user-groups`](#post-manage-user-groups)                                                            | authpy             | Change a user's groups                                                                                                                                                                                   |
| POST   | [`/parent-all-businesses`](#post-parent-all-businesses)                                                      | authpy             | List all of a site's groups                                                                                                                                                                              |
| POST   | [`/parent-other-businesses`](#post-parent-other-businesses)                                                  | authpy             | List a site's other groups (`getParentOtherBusinesses`)                                                                                                                                                  |
| POST   | [`/parent-user-businesses`](#post-parent-user-businesses)                                                    | authpy             | List a user's groups in a site                                                                                                                                                                           |
| POST   | [`/parent-users`](#post-parent-users)                                                                        | authpy             | List a site's users                                                                                                                                                                                      |
| POST   | [`/parent-users-temporary`](#post-parent-users-temporary)                                                    | authpy             | List a site's temporary users (v2)                                                                                                                                                                       |
| POST   | [`/parent-users-v2`](#post-parent-users-v2)                                                                  | authpy             | List a site's users (v2)                                                                                                                                                                                 |
| POST   | [`/remove-user-groups`](#post-remove-user-groups)                                                            | authpy             | Remove a user from groups (`blockUserGroupsFromClientApp`)                                                                                                                                               |
| POST   | [`/resend-invitation`](#post-resend-invitation)                                                              | authpy             | Resend an invitation                                                                                                                                                                                     |
| POST   | [`/revoke-invitation`](#post-revoke-invitation)                                                              | authpy             | Revoke an invitation                                                                                                                                                                                     |
| GET    | `/site/{parentUUID}/users`                                                                                   | authpy             | List a site's users (v3) (no caller)                                                                                                                                                                     |
| POST   | [`/user-token-jwt-device`](#post-user-token-jwt-device)                                                      | authpy             | List the user's signed-in devices (`listUserTokenJWTDevices`)                                                                                                                                            |

Notes on the table:

* `POST /v1/app/parents/add-user` has client code but no caller: web\_app\_v2's `AccountHttpService.addAccountAdmin` (web\_app\_v2 @ 0989b8e685, `src/app/services/account/account-http/account-http.service.ts:92-95`) is never called.
* The four apipy `/group_invite` routes are live (apipy @ 0e83c85e5a, `app.py:3068-3101`) and pass the body and the caller's token on to the php-apis actions `group_invitation`, `resend_group_invitation`, `delete_group_invitation` and `list_group_invitation` (`model/feature_php_api.py:91-105`). The only Android code that calls them, `callResendInvitedUserOLD` and `callDeleteInvitedUserOLD`, is commented out (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/BusinessUsersFragment.java:1390-1445`, `:1490-1550`).
* authpy's `POST /add-user` has client code but no caller: Android's `CreateUserProfileBottomSheet` (`app/src/main/java/gmail/com/snapfixapp/bottomSheet/CreateUserProfileBottomSheet.kt:703`) is only opened from a commented-out block (`fragment/ParentAccountUserFragment.kt:309-319`).
* The user's own on-call routes, `GET` and `PUT /v1/app/user/on-call-status`, are in [Account API](https://docs.snapfix.com/engineering-reference/api/account.md#get-v1appuseron-call-status).

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

Lists the users of one site: the members of its groups and the users linked to the site itself. The apps use it for the people pickers in chat, forwarding, filters and group user lists.

* **Auth:** user token. Any signed-in user; the route checks no membership of the site (api\_php\_live\_v2 @ ef3c4319f6, `routes/parents.php:18`, `app/Http/Controllers/v1/Versions/v1_0/App/ParentController.php:323-339`).
* **Used by:**
  * web\_app\_v2 @ 0989b8e685: `UserHttpService.getUserList` (`src/app/services/user/user-http/user-http.service.ts:84-91`), called for example from `src/app/pages/chat/chat.component.ts:663`, `src/app/components/filter-drawer/filter-users/filter-users.component.ts:194` and `src/app/pages/group-settings/group-settings-users/group-settings-account-users/group-settings-account-users.component.ts:161`; `ParentService.getAllUsers` (`src/app/services/parent/parent.service.ts:17-27`), called from `src/app/pages/comply/comply-contractors/comply-contractor/contractor-users/contractor-users.component.ts:108`.
  * iOS @ aa31967ac8 (`APIManager.PARENTS` + `/users`): `SVProgressHUD/Fire Store/FStoreHelper.swift:93`, `SnapFix/Chat/ChatMyNetworkVC/ChatMyNetworkVC.swift:90`, `SnapFix/Chat/CreateChat/CreateChatVC.swift:280`, `SnapFix/Chat/ForwardChat/ViewModel/ForwardChatViewModel.swift:7`, `SnapFix/Chat/RecentChatVC/RecentChatVC.swift:218`.
  * Android @ 86068bfeea (`parent_users_laravel`, with the site UUID in place of `XXXX`), under `app/src/main/java/gmail/com/snapfixapp/`: `bottomSheet/CreateChatBottomSheet.kt:218`, `bottomSheet/ForwardChatMessageBottomSheet.kt:204`, `fragment/ChatNetworkFragment.kt:106`, `fragment/HomeChatFragment.kt:836`.

**Request**

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

**Rules:** the list holds the users with a membership of one of the site's live groups, and the users with a row on the site, once each. Non-human users are left out, and so is a user whose every row on the site is deleted (`app/Services/ParentService.php:517-584`).

**Response** `200`: `data` is a list of [Site user objects](#site-user-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "username": "jane@example.com",
      "name": "Jane Example",
      "firstname": "Jane",
      "lastname": "Example",
      "countryCode": 44,
      "userType": "User",
      "mobile": "7700900123",
      "image": null,
      "tempUser": 0
    }
  ]
}
```

**Errors:** `400` "Invalid account" when the site has no groups (`ParentController.php:323-339`, `lang/en/messages.php:50`).

**Side effects:** none.

## GET /v1/app/staff-username

Lists the staff usernames of one site, newest first, deleted ones included (`app/Services/StaffUsernameService.php:17-47`).

* **Auth:** user token. The caller needs a live, unblocked row on the site named in `parentUuid` (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/StaffUsernameController.php:27-41`, `app/Services/UserParentService.php:190-197`). The caller's role is not checked.
* **Used by:** web\_app\_v2 @ 0989b8e685, `AccountHttpService.getAccountStaffUserList` (`src/app/services/account/account-http/account-http.service.ts:101-105`), called from `src/app/pages/account-settings/account-settings-staff/account-settings-staff.component.ts:80`.

**Request**

| Name         | In    | Type   | Required | Rules           |
| ------------ | ----- | ------ | -------- | --------------- |
| `parentUuid` | query | string | yes      | The site's UUID |

**Response** `200`: `data` is a list of [Staff username objects](#staff-username-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "userUuid": "123e4567-e89b-12d3-a456-426614174001",
      "staffUsername": "sam.staff",
      "name": "Sam Example",
      "firstname": "Sam",
      "lastname": "Example",
      "image": null,
      "createdTs": 1763000000000,
      "modifiedTs": 1763000000000,
      "requestPasswordReset": 0,
      "requestTs": null
    }
  ]
}
```

**Errors:** `400` "Invalid user account" when the caller has no live, unblocked row on the site (`StaffUsernameController.php:34-35`, `lang/en/messages.php:52`); `422` when `parentUuid` is missing.

**Side effects:** none.

## POST /v1/app/staff-username

Creates a staff user: a new account with a staff username and a password, made an admin of one group. The web's staff settings use it to add staff who sign in with a staff username.

* **Auth:** user token. The caller needs a live, unblocked row on the site named in `parentUuid` (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/StaffUsernameController.php:53-97`). Nothing checks the caller's role, or that `businessUuid` belongs to that site.
* **Used by:** web\_app\_v2 @ 0989b8e685, `AccountHttpService.createAccountStaffUser` (`src/app/services/account/account-http/account-http.service.ts:110-114`), called from `src/app/pages/account-settings/account-settings-staff/account-settings-staff-dialog/account-settings-staff-dialog.component.ts:70`.

**Request** (`app/Http/Requests/v1/StaffUsername/CreateStaffUsernameRequest.php:15-60`)

| Name            | In   | Type    | Required | Rules                                                                                        |
| --------------- | ---- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| `parentUuid`    | body | string  | yes      | The site; used only for the caller check                                                     |
| `businessUuid`  | body | string  | yes      | The group that gets the new admin; not checked against `parentUuid`                          |
| `staffUsername` | body | string  | yes      | Must not match a live user's staff username: "Staff username already exists!"                |
| `password`      | body | string  | yes      | At least 8 characters, with a digit, a lower-case and an upper-case letter. Stored as a hash |
| `firstname`     | body | string  | no       | First name                                                                                   |
| `lastname`      | body | string  | no       | Last name                                                                                    |
| `imageUrl`      | body | string  | no       | Photo URL                                                                                    |
| `username`      | body | string  | no       | Sign-in email address                                                                        |
| `countryCode`   | body | numeric | no       | Country code                                                                                 |
| `mobile`        | body | numeric | no       | Mobile number                                                                                |

**Response** `200`: `data` is `null`, with the default message "Operation was successful".

**Errors:** `400` "Invalid user account" when the caller has no live, unblocked row on the site; `422` for a failed rule, such as "Staff username already exists!".

**Side effects:**

* Creates a [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row with the staff username, origin web admin and the caller as creator, and a [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) row with the password hash and salt.
* Makes the new user an active admin of `businessUuid` ([`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md)). The new user gets no row on the site.
* Adds a [`staff_username`](https://docs.snapfix.com/engineering-reference/db/tables/staff_username.md) row with a proxy email of the form `<staffUsername>@cognito.aws` and the caller as proxy admin.

## POST /v1/app/user/add-relation/{item\_uuid}

Adds existing users to one group, each with the role User.

* **Auth:** user token. The caller must pass `updateBusinessUsers` on the group: a site admin, a multi-site user of the site, or a group admin or holder of the edit-users permission who is not read-only (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/UserAssetBusinessController.php:37-83`, `app/Policies/BusinessPolicy.php:101-118`). The listed users are not checked against the group's site.
* **Used by:**
  * web\_app\_v2 @ 0989b8e685, `GroupHttpService.addGroupUsers` (`src/app/services/group/group-http/group-http.service.ts:240-246`), called from `src/app/pages/group-settings/group-settings-users/group-settings-account-users/group-settings-account-users.component.ts:142`, `src/app/pages/multisite-console/users/multisite-user-access/groups-tab/multisite-user-access-groups-tab.component.ts:433` and `src/app/services/multisite-console/multisite-helper/multisite-helper.service.ts:33`.
  * snapfix\_ai\_agent @ e5e18caef5, `add_users` (`src/snapfix/businesses/__init__.py:69-77`, form field `usersUuids[]`).

**Request**

| Name         | In   | Type             | Required | Rules                                                                                |
| ------------ | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------ |
| `item_uuid`  | path | string           | yes      | The group's UUID; unknown gives `404`                                                |
| `usersUuids` | body | array of strings | yes      | User UUIDs (`app/Http/Requests/v1/BusinessUser/CreateUserBusinessRequest.php:15-37`) |

**Response** `200`: `data` is a list of [Group member objects](#group-member-object), one for each user written.

```json
{
  "status": "success",
  "message": "User added to the business successfully",
  "data": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "isSystem": false,
      "relationUuid": "123e4567-e89b-12d3-a456-426614174002",
      "name": "Jane Example",
      "firstname": "Jane",
      "lastname": "Example",
      "address": "Room 101",
      "staffUsername": null,
      "image": null,
      "username": "jane@example.com",
      "countryCode": 44,
      "mobile": "7700900123",
      "relationDeleted": 0,
      "active": 1,
      "role": "User",
      "user_type": "normal",
      "onboard": "Active",
      "notificationDisabled": 0,
      "tempUser": 0,
      "permissions": {"perJobViewAll": 1}
    }
  ]
}
```

**Errors:** `403` "Access denied" without `updateBusinessUsers`; `404` "Resource not found" for an unknown group; `422` when `usersUuids` is missing or not a list of strings.

**Side effects:**

* For each user, the newest membership of the group, deleted or not, is restored and set to User and Active; only a user who never had one gets a new [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row (`app/Services/UserAssetBusinessService.php:39-82`, `:127-143`). So adding a current member, an admin included, resets that member to User.
* A deleted row of the user on the group's site is restored with the type `user`.
* Sends each added user a push notification that names the caller and the group, a silent update to the group's devices, and the site's new user count to Firebase (`user_count`).

## GET /v1/app/user/get-role

Returns the signed-in user's role in one site: `account_admin`, `group_admin` or `user`. The web sends it to Survicate as a survey attribute and uses it for nothing else.

* **Auth:** user token. Returns only the caller's own role.
* **Used by:** web\_app\_v2 @ 0989b8e685, `SurvicateService.getUserRole` (`src/app/services/survicate/survicate.service.ts:260-267`), called from eleven pages, for example `src/app/pages/task-list/task-list.component.ts:295` and `src/app/pages/dashboard-reports/dashboard/dashboard.component.ts:44`.

**Request**

| Name         | In    | Type   | Required | Rules                              |
| ------------ | ----- | ------ | -------- | ---------------------------------- |
| `parentUuid` | query | string | yes      | The site's UUID (`GetRoleRequest`) |

**Rules** (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/UserController.php:64-87`):

* `account_admin`: the caller's newest live row on the site has the type `admin` (`app/Services/UserParentService.php:148-156`). A blocked row counts.
* `group_admin`: otherwise, when any of the caller's memberships in the site's groups has the Admin role. Deleted memberships and deleted groups count too (`app/Services/UserAssetBusinessService.php:593-628`, `withTrashed`), so a former group admin still gets `group_admin`.
* `user`: neither, including a site the caller does not belong to.

**Response** `200`: `data` is `{"role": "..."}`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {"role": "group_admin"}
}
```

**Errors:** `422` when `parentUuid` is missing.

**Side effects:** none.

## POST /v1/app/user/multi

Returns several users by UUID, for names and photos in chats.

* **Auth:** user token. Only users who have a live membership of a group the caller is also a live member of are returned; the Snapbot caller gets any user with a live membership (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/UserService.php:58-92`). The Snapbot and system users are returned whenever they are named.
* **Used by:**
  * web\_app\_v2 @ 0989b8e685, `UserHttpService.getMutliUserbyIds` (`src/app/services/user/user-http/user-http.service.ts:282-288`), called from `src/app/services/chat/chat-data.service.ts:143` and `src/app/services/chat/chat-helper/chat-helper.service.ts:1713`.
  * Android @ 86068bfeea, `user_multi` in `getSnapBotQrUsers` (`app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:4904-4912`, reached from `:581`).

**Request**

| Name    | In   | Type             | Required | Rules                            |
| ------- | ---- | ---------------- | -------- | -------------------------------- |
| `uuids` | body | array of strings | yes      | User UUIDs (`MultiUsersRequest`) |

**Response** `200`: `data` is a list of [User objects](https://docs.snapfix.com/engineering-reference/api/account.md#user-object). Here `userType` is always `User` and `userParentDeleted` is `null`, because the query loads no site row.

**Errors:** `422` when `uuids` is missing or not a list of strings.

**Side effects:** none.

Co-members get each other's address and mobile number \[[ASK-72](https://github.com/snapfix/docs/blob/main/ASK.md#ask-72-should-every-member-get-the-other-members-and-invitees-contact-details)].

## POST /v1/app/user/on-call

Lists the users on call in each site named.

* **Auth:** user token. The route checks no membership of the sites (api\_php\_live\_v2 @ ef3c4319f6, `routes/user.php:29`, `app/Http/Controllers/v1/Versions/v1_0/App/UserController.php:374-394`).
* **Used by:**
  * web\_app\_v2 @ 0989b8e685, `UserHttpService.getOnCallUsers` (`src/app/services/user/user-http/user-http.service.ts:45-57`), called from `src/app/components/side-menu/account-list-menu/account-list-menu.component.ts:340`.
  * snapfix\_ai\_agent @ e5e18caef5, `on_call_users` (`src/snapfix/users/__init__.py:24-33`), which checks the site itself first.

**Request**

| Name          | In   | Type             | Required | Rules                                                 |
| ------------- | ---- | ---------------- | -------- | ----------------------------------------------------- |
| `parentUuids` | body | array of strings | yes      | Site UUIDs; no upper limit (`ReadOnCallUsersRequest`) |

**Rules:** the route loads each site and its on-call users one after the other, two queries per site, with no cap on the number of sites. A user is on call when the user's live row on the site has `on_call` set (`app/Models/ParentModel.php:172-187`).

**Response** `200`: `data` is a list of [On-call list objects](#on-call-list-object), one per site in the order sent.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "parentUuid": "123e4567-e89b-12d3-a456-426614174003",
      "onCallUsers": [
        {
          "uuid": "123e4567-e89b-12d3-a456-426614174000",
          "username": "jane@example.com",
          "name": "Jane Example",
          "firstname": "Jane",
          "lastname": "Example",
          "countryCode": 44,
          "mobile": "7700900123",
          "image": null,
          "address": "Room 101",
          "language": "en",
          "emailVerified": 1,
          "mobileVerified": 0,
          "notes": null,
          "showAiAgentTooltip": 0,
          "userType": "User",
          "userParentDeleted": null
        }
      ]
    }
  ]
}
```

**Errors:** `404` "Resource not found" when a site is unknown (the whole call fails); `422` when `parentUuids` is missing.

**Side effects:** none.

## POST /v1/app/user/start-app

Logs that the signed-in user started the web app, with the app version and IP data. The mobile apps log starts through php-apis `save_pri_log_startappuser`.

* **Auth:** user token. The row is written for the token's user (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/StartAppUserController.php:18-31`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `AuthHttpService.saveAuthUserLog` (`src/app/services/auth/auth-http/auth-http.service.ts:72-82`), called from `src/app/services/auth/auth-helper/auth-helper.service.ts:119`, which runs at sign-in (`:42`).

**Request** (`CreateStartAppUserRequest`)

| Name         | In   | Type   | Required | Rules                                                   |
| ------------ | ---- | ------ | -------- | ------------------------------------------------------- |
| `appVersion` | body | string | yes      | The web sends its version with `_` and its origin added |
| `ipData`     | body | object | yes      | The IP lookup result; each value a string or `null`     |

**Response** `200`: `data` is `null`, `message` "StartAppUser log created successfully".

**Errors:** `422` when `appVersion` or `ipData` is missing.

**Side effects:** one [`tPri_Log_StartAppUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_startappuser.md) row with the caller, the app version and the IP data as JSON.

## DELETE /v1/app/user/{invite\_id}/invite-cancel/{item\_uuid}

Cancels a pending invitation to a group.

* **Auth:** user token. The caller must pass `updateBusinessUsers` on the group named by `item_uuid`. The invitation is then loaded by its UUID alone, so the caller can cancel an invitation to any group (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/UserInviteController.php:158-176`, `app/Services/UserInviteService.php:25-28`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `GroupHttpService.deleteGroupInvitation` (`src/app/services/group/group-http/group-http.service.ts:269-273`), called from `src/app/pages/group-settings/group-settings-users/group-settings-invited-users/group-settings-invited-users.component.ts:94`.

**Request**

| Name        | In   | Type   | Required | Rules                 |
| ----------- | ---- | ------ | -------- | --------------------- |
| `invite_id` | path | string | yes      | The invitation's UUID |
| `item_uuid` | path | string | yes      | The group's UUID      |

**Response** `200`: `data` is `null`, `message` "Invitation deleted successfully".

**Errors:** `403` "Access denied" without `updateBusinessUsers`; `404` "Resource not found" for an unknown group or invitation.

**Side effects:** marks the [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) row deleted (`fDeleted`, `app/Models/BaseModel.php:15-22`).

## PUT /v1/app/user/{invite\_id}/invite-resend/{item\_uuid}

Sends a pending group invitation again, the same way it was first sent.

* **Auth:** user token. The caller must pass `updateBusinessUsers` on the group named by `item_uuid`; the invitation is not checked against that group (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/UserInviteController.php:129-146`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `GroupHttpService.resendGroupUserInvitation` (`src/app/services/group/group-http/group-http.service.ts:258-262`, empty body), called from `src/app/pages/group-settings/group-settings-users/group-settings-invited-users/group-settings-invited-users.component.ts:55`.

**Request**

| Name        | In   | Type   | Required | Rules                 |
| ----------- | ---- | ------ | -------- | --------------------- |
| `invite_id` | path | string | yes      | The invitation's UUID |
| `item_uuid` | path | string | yes      | The group's UUID      |

**Response** `200`: `data` is the [Invitation object](#invitation-object), `message` "Invitation sent successfully".

```json
{
  "status": "success",
  "message": "Invitation sent successfully",
  "data": {
    "uuid": "123e4567-e89b-12d3-a456-426614174004",
    "countryCode": null,
    "mobile": null,
    "username": "jane@example.com",
    "invitedEmail": 2,
    "invitedSms": null
  }
}
```

**Errors:** `403` "Access denied" without `updateBusinessUsers`; `404` "Resource not found" for an unknown group or invitation.

**Side effects** (`app/Services/UserInviteService.php:145-172`):

* Queues an invitation email with the inviter's name when the invitation went by email before; otherwise a WhatsApp message when it went by WhatsApp; otherwise an SMS.
* Raises that channel's send count on the [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) row and stores the `fOrigin` request header as its origin.

## DELETE /v1/app/user/{user\_uuid}/remove-relation/{item\_uuid}

Removes a member from a group. The route also accepts a trailing slash (`routes/user.php:35`).

* **Auth:** user token. The caller must pass `updateBusinessUsers` on the group (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/UserAssetBusinessController.php:153-193`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `GroupHttpService.deleteGroupUser` (`src/app/services/group/group-http/group-http.service.ts:230-234`), called from `src/app/pages/group-settings/group-settings-users/group-settings-group-users/group-settings-group-users.component.ts:141`.

**Request**

| Name        | In   | Type   | Required | Rules             |
| ----------- | ---- | ------ | -------- | ----------------- |
| `user_uuid` | path | string | yes      | The member's UUID |
| `item_uuid` | path | string | yes      | The group's UUID  |

**Response** `200`: `data` is `null`, `message` "User removed from the business successfully".

**Errors:** `403` "Access denied" without `updateBusinessUsers`; `404` "Resource not found" for an unknown group, or a user with no membership of it (`app/Services/UserAssetBusinessService.php:182-196`).

**Side effects:**

* Marks the user's live [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row for the group deleted (the most recently changed one, if there are several).
* Sends a silent update to the group's devices and the site's new user count to Firebase.
* Keeps the user's task assignments: the code that removed them is commented out, "Disabling this action for now" (`UserAssetBusinessController.php:168-169`) \[[ASK-75](https://github.com/snapfix/docs/blob/main/ASK.md#ask-75-should-removing-a-member-take-them-off-their-tasks)].
* Nothing stops the last active admin from being removed.

## PUT /v1/app/user/{user\_uuid}/update-relation/{item\_uuid}

Changes a member's role, onboarding state and permissions in one group.

* **Auth:** user token. The caller must pass `updateBusinessUsers` on the group, and may change their own membership too (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/UserAssetBusinessController.php:99-137`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `GroupHttpService.updateGroupUser` (`src/app/services/group/group-http/group-http.service.ts:215-222`), called from `src/app/pages/group-settings/group-settings-users/group-settings-user-edit-dialog/group-settings-user-edit-dialog.component.ts:92`, `src/app/pages/multisite-console/users/multisite-user-access/groups-tab/multisite-user-access-groups-tab.component.ts:421`, `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-access/account-settings-manage-user-groups/account-settings-manage-user-groups.component.ts:301` and `src/app/services/multisite-console/multisite-helper/multisite-helper.service.ts:39`.

**Request** (`app/Http/Requests/v1/BusinessUser/UpdateUserBusinessRequest.php:15-30`)

| Name            | In   | Type    | Required | Rules                                                                                                              |
| --------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `user_uuid`     | path | string  | yes      | The member's UUID                                                                                                  |
| `item_uuid`     | path | string  | yes      | The group's UUID                                                                                                   |
| `role`          | body | string  | yes      | `Admin` or `User`                                                                                                  |
| `onboard`       | body | string  | no       | `Active` or `Inactive`                                                                                             |
| permission keys | body | boolean | no       | Any key of the `Permission` enum, such as `perJobViewAll` or `perBusSettingsEditUser` (`app/Enums/Permission.php`) |

**Response** `200`: `data` is one [Group member object](#group-member-object), `message` "User relation updated successfully".

**Errors:** `403` "Access denied" without `updateBusinessUsers`; `404` "Resource not found" for an unknown group or a user with no membership; `422` for an unknown `role` or `onboard`, or a permission that is not a boolean.

**Side effects:** updates the user's live [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row for the group and sends a silent update to the group's devices. Nothing stops the last active admin from being demoted.

## POST /add-user-groups-v2

Adds users to groups of a site, with a role in each group. The web calls it from the site and multi-site user screens.

* **Auth:** user token; [site admin check](#users-api) (authpy @ 5d5758661c, `app.py:2247-2266`, `model/feature_token_ops.py:3766-3792`). The groups are not checked against `parentUUID`, here or in php-apis.
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.addManageUserGroup` (`src/app/services/user/user-http/user-http.service.ts:198-205`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-access/account-settings-manage-user-groups/account-settings-manage-user-groups.component.ts:270` and `src/app/pages/multisite-console/users/multisite-user-access/groups-tab/multisite-user-access-groups-tab.component.ts:385`.

**Request** (JSON; shape as in `ManageUserGroupAddDTO`, `src/app/models/user/user.model.dto.ts:16-25`)

| Name         | Type   | Required | Rules                                                                                                                    |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `parentUUID` | string | yes      | The site                                                                                                                 |
| `userGroups` | array  | yes      | Items `{userUUID, groups}`, where `groups` is a list of `{uuid, usertype}`: a group UUID and the Admin or User role UUID |

authpy sends `userGroups` and the caller on to [proxy\_add\_userbusiness\_v2](#post-actionproxy_add_userbusiness_v2).

**Response** `200`: always `{"result": true, "message": "success", "serverTs": ...}` once the caller check passes. authpy does not read the php-apis answer, so a failed or partial write also answers success.

**Errors:** `invalid params` when `parentUUID` or `userGroups` is missing or empty; `unauthorised access`.

**Side effects:** as in [proxy\_add\_userbusiness\_v2](#post-actionproxy_add_userbusiness_v2): adds or changes [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows.

## POST /add-user-v2

Adds one user to a site and to groups, from the apps' add-user screens. The answer comes first; php-apis creates the user after it.

* **Auth:** user token. The caller must be a site admin of `parentUUID`, a live admin of any live group of that site, or a multi-site member covering it (authpy @ 5d5758661c, `app.py:2312-2332`, `model/feature_token_ops.py:3486-3504`). The groups in the request are not checked against that site, so a group admin of one site can add users to another.
* **Used by:** Android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/bottomSheet/AddUserViaPhoneEmailBottomSheet.kt:378`; iOS @ aa31967ac8, `SnapFix/AddUser/AddUserSharedData.swift:135`.

**Request** (JSON): `parentUUID` (required) and the fields of [proxy\_add\_user\_v2](#post-actionproxy_add_user_v2): `firstname`, `origin` and `groups` (a list of `{uuid, usertype}`), and `email` or `countrycode` with `mobile`; optional `lastname` and `user_type`. authpy adds `logged_in_user` from the token.

**Response** `200`: the php-apis answer, passed on; on success `result: true` and "Request to create users is accepted and will be processed shortly.".

**Errors:** `invalid params` when `parentUUID` is missing; `unauthorised access`; the php-apis messages of [proxy\_add\_user\_v2](#post-actionproxy_add_user_v2).

**Side effects:** as in [proxy\_add\_user\_v2](#post-actionproxy_add_user_v2), after the answer.

## POST /add-users

Adds a list of users to a site. The web uploads the list as a JSON file, then calls this route with the file's URL.

* **Auth:** user token. The same callers as [POST /add-user-v2](#post-add-user-v2), with the same gap for group admins (authpy @ 5d5758661c, `app.py:2334-2354`, `model/feature_token_ops.py:3506-3528`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.createUsers` (`src/app/services/user/user-http/user-http.service.ts:252-257`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-create-dialog/account-settings-manage-user-create-dialog.component.ts:119`.

**Request** (JSON)

| Name         | Type   | Required | Rules                                                                                                                                                                                                                              |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUUID` | string | yes      | The site                                                                                                                                                                                                                           |
| `origin`     | string | yes      | Where the request comes from                                                                                                                                                                                                       |
| `users`      | string | yes      | The URL of a JSON file with the users, in the item shape of [proxy\_add\_users](#post-actionproxy_add_users). php-apis fetches whatever URL is sent (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7412`) |

**Response** `200`: the php-apis answer, passed on; on success `result: true` and "Request to create users is accepted and will be processed shortly.".

**Errors:** `invalid params` when a required field is missing; `unauthorised access`; the php-apis messages of [proxy\_add\_users](#post-actionproxy_add_users), such as the bulk-upload limit for sites that do not pay.

**Side effects:** as in [proxy\_add\_users](#post-actionproxy_add_users), after the answer.

## POST /block-devices-v2

Blocks or unblocks devices at a site: signs a device out, or lets it back in.

* **Auth:** user token; [site admin check](#users-api) (authpy @ 5d5758661c, `app.py:2143-2170`, `model/feature_token_ops.py:940-954`). The devices are not checked against the site.
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.manageUserDeviceAction` (`src/app/services/user/user-http/user-http.service.ts:216-222`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-access/user-devices/user-devices.component.ts:68` and `:102`; Android @ 86068bfeea, `loggedOutFromDevices` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:630`); iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/BottomSheet/BlockDeviceActionVC.swift:154`.

**Request** (JSON)

| Name               | Type             | Required       | Rules                                                                                             |
| ------------------ | ---------------- | -------------- | ------------------------------------------------------------------------------------------------- |
| `parentUUID`       | string           | yes            | The site                                                                                          |
| `blockDeviceIDs`   | array of strings | one of the two | Device IDs to block, as `device_id` in [POST /user-token-jwt-device](#post-user-token-jwt-device) |
| `unBlockDeviceIDs` | array of strings | one of the two | Device IDs to unblock                                                                             |

**Response** `200`: `result: true` with "Device(s) blocked succcessfully", "Device(s) unblocked succcessfully" or "Few devices blocked and other few unblocked succcessfully", by the lists sent.

**Errors:** `invalid params` when both lists are empty or `parentUUID` is missing; `unauthorised access`.

**Side effects** (`model/feature_token_ops.py:956-1140`):

* **Block:** blocks every live token of the listed devices, access and refresh, for every user and site, by device ID alone. Then sets each device's [`tPri_ParentDevice`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentdevice.md) row for the site to blocked, or adds one, with a note that names the admin. When some listed devices have live tokens and others do not, the devices without tokens get no row, so their block is not stored.
* **Unblock:** blocks the devices' live access tokens, which signs them out \[[ASK-231](https://github.com/snapfix/docs/blob/main/ASK.md#ask-231-should-unblocking-a-device-or-a-user-cut-its-current-access-tokens)], then sets their rows to unblocked. Unblocking a device that is already unblocked fails after its tokens are blocked.

## POST /block-users

Blocks or unblocks users at a site.

* **Auth:** user token; [site admin check](#users-api) (authpy @ 5d5758661c, `app.py:2172-2200`, `model/feature_token_ops.py:1142-1157`). The users are not checked against the site.
* **Used by:** Android @ 86068bfeea, `blockUnblockUser` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:450`, called from `fragment/ParentAccountUserFragment.kt:801` and `:814`); iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/ManageUsers/ManageUsersVC+APICalls.swift:106`. The web defines `BLOCK_USERS` but never calls it.

**Request** (JSON)

| Name               | Type             | Required       | Rules            |
| ------------------ | ---------------- | -------------- | ---------------- |
| `parentUUID`       | string           | yes            | The site         |
| `blockUserUUIDs`   | array of strings | one of the two | Users to block   |
| `unBlockUserUUIDs` | array of strings | one of the two | Users to unblock |

**Response** `200`: `result: true` with "User blocked succcessfully", "User unblocked succcessfully" or "Few users blocked and other few unblocked succcessfully".

**Errors:** `invalid params` when both lists are empty or `parentUUID` is missing; `unauthorised access`.

**Side effects** (`model/feature_token_ops.py:1158-1345`):

* **Block:** blocks the users' live access tokens, for every site; refresh tokens stay valid. Sets the user's live [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row for the site to blocked; a user with no row there gets a new blocked row of type `normal`. When some listed users have live tokens and others do not, the users without tokens get no row.
* **Unblock:** blocks the users' live access tokens as well, so they sign in again \[[ASK-231](https://github.com/snapfix/docs/blob/main/ASK.md#ask-231-should-unblocking-a-device-or-a-user-cut-its-current-access-tokens)], then sets their rows to unblocked. A listed user with no live row on the site gets a new, unblocked row of type `normal` (`:1291-1306`, `:1326-1341`), which makes that user a member of the site.

## POST /manage-user-groups

Adds a user to some groups and removes them from others, in one call. The apps use it on the user's group screen.

* **Auth:** user token; [site admin check](#users-api) (authpy @ 5d5758661c, `app.py:2268-2288`, `model/feature_token_ops.py:3794-3818`). The groups are not checked against `parentUUID`.
* **Used by:** Android @ 86068bfeea, `removeUserFromGroup` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:384`, called from `fragment/ParentAccountUserFragment.kt:673`); iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/BottomSheet/RemoveFromGroupActionVCViewModel.swift:111`.

**Request** (JSON)

| Name             | Type             | Required       | Rules                                                                  |
| ---------------- | ---------------- | -------------- | ---------------------------------------------------------------------- |
| `parentUUID`     | string           | yes            | The site                                                               |
| `userUUID`       | string           | yes            | The user whose groups change                                           |
| `groupsToAdd`    | array            | one of the two | Items `{uuid, usertype}`: a group UUID and the Admin or User role UUID |
| `groupsToRemove` | array of strings | one of the two | Group UUIDs                                                            |

authpy sends the body, with the caller as `login_user_uuid`, to [proxy\_manage\_userbusiness](#post-actionproxy_manage_userbusiness).

**Response** `200`: the php-apis answer, passed on, such as "User added to 2 group(s) and removed from 1 group(s)." (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7242-7302`).

**Errors:** `invalid params`; `unauthorised access`; the php-apis messages, such as "invalid group params".

**Side effects:** as in [proxy\_manage\_userbusiness](#post-actionproxy_manage_userbusiness): adds memberships and marks removed ones deleted in [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md).

## POST /parent-all-businesses

Lists the groups of a site with one user's membership of each. The group screens use it.

* **Auth:** user token. The caller must be a site admin of `parentUUID`, a live admin of a live group of that site, who then sees only the groups they administer, or a multi-site member covering the site (authpy @ 5d5758661c, `app.py:2101-2120`, `model/feature_token_ops.py:3315-3425`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.getManageUserGroupList` (`src/app/services/user/user-http/user-http.service.ts:170-180`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-access/account-settings-manage-user-groups/account-settings-manage-user-groups.component.ts:216`, `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-create-dialog/manage-users-create-group-list/manage-users-create-group-list.component.ts:146` and `src/app/pages/multisite-console/users/multisite-user-access/groups-tab/multisite-user-access-groups-tab.component.ts:316`; Android @ 86068bfeea, `getParentBusinessList` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:174`); iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/BottomSheet/RemoveFromGroupActionVCViewModel.swift:28`.

**Request** (JSON)

| Name         | Type   | Required | Rules                                |
| ------------ | ------ | -------- | ------------------------------------ |
| `parentUUID` | string | yes      | The site                             |
| `userUUID`   | string | yes      | The user whose memberships are shown |

**Response** `200`: `data` is a list of [Site group objects](#site-group-object), one per live group of the site the caller may see, ordered by name, with the membership fields filled.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": [
    {
      "fName": "Room 101 Team",
      "fImage": "",
      "uuid_tBusiness": "123e4567-e89b-12d3-a456-426614174005",
      "enum_BusinessType": "task",
      "uuid_tUserBusiness": "123e4567-e89b-12d3-a456-426614174006",
      "uuid_tUserType": "123e4567-e89b-12d3-a456-426614174007",
      "uuid_tUser": "123e4567-e89b-12d3-a456-426614174000",
      "user_role": "User",
      "business_disabled": 0
    }
  ]
}
```

**Errors:** `invalid params` when `parentUUID` or `userUUID` is missing; `unauthorised access`; `no groups found`.

**Side effects:** none.

## POST /parent-other-businesses

Lists the groups of a site that a user is not in. The apps' add-user screens use it to offer groups; they send a random `userUUID`, so they get every group the caller may see.

* **Auth:** user token. The same callers as [POST /parent-all-businesses](#post-parent-all-businesses): a group admin sees only the groups they administer (authpy @ 5d5758661c, `app.py:2080-2099`, `model/feature_token_ops.py:3256-3313`).
* **Used by:** Android @ 86068bfeea, `BusinessViewModel.getParentOtherBusinessList` (`app/src/main/java/gmail/com/snapfixapp/viewModels/BusinessViewModel.java:1086-1101`), called from `bottomSheet/AddUserViaPhoneEmailBottomSheet.kt:285` and `bottomSheet/AddUserViaQRBottomSheet.kt:151`; iOS @ aa31967ac8, `SnapFix/AddUser/AddUserSharedData.swift:81`. The web defines `PARENT_OTHER_BUSINESSES` but never calls it.

**Request** (JSON): `parentUUID` and `userUUID`, both required, as in [POST /parent-all-businesses](#post-parent-all-businesses).

**Response** `200`: `data` is a list of [Site group objects](#site-group-object) with `fName`, `fImage`, `uuid_tBusiness` and `enum_BusinessType` only, ordered by name.

**Errors:** `invalid params`; `unauthorised access`; `no other groups found`.

**Side effects:** none.

## POST /parent-user-businesses

Lists the groups of a site that a user is in. Android reads it before it removes a user from a site.

* **Auth:** user token; [site admin check](#users-api). Group admins are not accepted (authpy @ 5d5758661c, `app.py:2059-2078`, `model/feature_token_ops.py:3213-3254`).
* **Used by:** Android @ 86068bfeea, `deleteUser` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:539-560`, called from `fragment/ParentAccountUserFragment.kt:773`), which then calls [POST /remove-user-groups](#post-remove-user-groups). iOS defines `PARENT_USERS_BUSINESS` but never calls it.

**Request** (JSON): `parentUUID` and `userUUID`, both required.

**Response** `200`: `data` is a list of [Site group objects](#site-group-object) with `fName`, `fImage`, `uuid_tBusiness`, `user_role` and `enum_BusinessType`, one per live membership of the user in a live group of the site, ordered by name.

**Errors:** `invalid params`; `unauthorised access`; `no user groups found`.

**Side effects:** none.

## POST /parent-users

Lists the users of a site, a page at a time, without a total.

* **Auth:** user token. The membership check is commented out, so any signed-in user can list any site's users (authpy @ 5d5758661c, `app.py:1767-1785`, `model/feature_token_ops.py:1527-1736`, check at `:1534-1536`).
* **Used by:** Android @ 86068bfeea, `getParentUserList` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:73`) and `fragment/HomeChatFragment.kt:624` and `:655`; iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/ManageUsers/ManageUsersViewModel.swift:30`.

**Request** (JSON)

| Name         | Type    | Required | Rules                                                                                                                       |
| ------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `parentUUID` | string  | yes      | The site                                                                                                                    |
| `offset`     | integer | no       | Default `0`                                                                                                                 |
| `limit`      | integer | no       | Default `50`, no upper limit                                                                                                |
| `search`     | string  | no       | Matches, ignoring case, the name, first name, last name, username, country code, mobile number, user UUID or staff username |

**Rules:** the list holds users who are not deleted and have a live membership of a live group of the site, or a live row on the site. A user with a temporary password is listed only after a first sign-in, with Snapfix or single sign-on. Admins come first, then the list is sorted by first name. One fixed user is always left out.

**Response** `200`: `data` is a list of [Site user objects (authpy)](#site-user-object-authpy), or `[]`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": [
    {
      "fFirstName": "Jane",
      "fLastName": "Example",
      "fName": "Jane Example",
      "fImage": "",
      "fUsername": "jane@example.com",
      "fCountryCode": "44",
      "fMobile": "7700900123",
      "uuid_tUser": "123e4567-e89b-12d3-a456-426614174000",
      "user_type": "admin",
      "blocked": 0,
      "last_activity_ts": 0
    }
  ]
}
```

**Errors:** `invalid params` when `parentUUID` is missing; a value of `offset` or `limit` that is not a number answers with Python's conversion error text.

**Side effects:** none.

## POST /parent-users-temporary

Lists the pending invitations of a site: the live, unblocked rows on the site of users who still have a temporary password and have never signed in. The user management screens show them as invited users.

* **Auth:** user token. The membership check is commented out, so any signed-in user can list any site's invitations, with their invitation links (authpy @ 5d5758661c, `app.py:2035-2057`, `model/feature_token_ops.py:3066-3211`, check at `:3073-3075`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.getManageInvitedUserList` (`src/app/services/user/user-http/user-http.service.ts:144-163`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-list/account-settings-manage-user-list.component.ts:288`; Android @ 86068bfeea, `getParentInvitedUserList` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:127`); iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/ManageUsers/ManageUsersViewModel.swift:58`.

**Request** (JSON): the fields of [POST /parent-users](#post-parent-users), with the same defaults and search fields.

**Response** `200`: `data` is `{"items": [...], "total": n}`, with [Invited user objects](#invited-user-object) sorted by first name, or `[]` when there are none.

**Errors:** `invalid params` when `parentUUID` is missing.

**Side effects:** none.

## POST /parent-users-v2

Lists the users of a site, a page at a time, with the total. The web's user management screen and the housekeeping planner use it.

* **Auth:** user token. The membership check is commented out (authpy @ 5d5758661c, `app.py:1788-1809`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.getManageUserList` (`src/app/services/user/user-http/user-http.service.ts:123-142`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-list/account-settings-manage-user-list.component.ts:295` and `src/app/services/housekeeping/housekeeping-helper/housekeeping-helper.service.ts:265`.

**Request** (JSON): as in [POST /parent-users](#post-parent-users).

**Response** `200`: `data` is `{"items": [...], "total": n}`, with the items of [POST /parent-users](#post-parent-users); `total` counts the users that match before paging. `data` is `[]` when no user matches.

**Errors:** as in [POST /parent-users](#post-parent-users).

**Side effects:** none.

## POST /remove-user-groups

Removes users from groups, or removes one user from a site.

* **Auth:** user token; [site admin check](#users-api) (authpy @ 5d5758661c, `app.py:2205-2224`, `model/feature_token_ops.py:1347-1362`). The groups are not checked against `parentUUID`.
* **Used by:**
  * web\_app\_v2 @ 0989b8e685: `UserHttpService.removeManageUserGroup` (`src/app/services/user/user-http/user-http.service.ts:207-213`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-access/account-settings-manage-user-groups/account-settings-manage-user-groups.component.ts:286` and `src/app/pages/multisite-console/users/multisite-user-access/groups-tab/multisite-user-access-groups-tab.component.ts:402`; `UserHttpService.removeManageUser` (`:225-231`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-users-header/account-settings-manage-users-header.component.ts:130`.
  * Android @ 86068bfeea, `removeUserFromParent` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:200-212`), reached through `deleteUser` (`:545`, `:560`).
  * iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/BottomSheet/RemoveFromGroupActionVCViewModel.swift:79`.

**Request** (JSON): `parentUUID`, and one of two forms.

| Form   | Fields                                              | Meaning                                                                                     |
| ------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Groups | `userGroups`: a list of `{userUUID, businessUUIDs}` | Removes each user from the listed groups                                                    |
| Site   | `userUUIDToRemove` and `removeUserParent: 1`        | Removes the user from all the site's groups and from the site; `userGroups` is then ignored |

**Response** `200`: `{"result": true, "message": "success", "serverTs": ...}`.

**Errors:** `invalid params` when `parentUUID` is missing or neither form is complete; `unauthorised access`; a failed write answers with the database's error text.

**Side effects:**

* Groups form: marks the user's live [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows in the listed groups deleted, with a note that names the admin (`:1413-1415`).
* Site form: marks the user's live memberships of the site's groups and the user's live [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) rows on the site deleted (`:1364-1388`).
* Both forms put `userUUID`, `businessUUIDs` and `userUUIDToRemove` into the `UPDATE` text as they are, without parameters (`:1386`, `:1415`; `model/utils.py:226-238`), so a value with a quote changes the statement.
* The user's tokens stay valid: the code that blocked them is commented out (`:1417-1494`).

## POST /resend-invitation

Sends a site invitation again. The user management screens call it from the invited users list.

* **Auth:** user token; [site admin check](#users-api) (authpy @ 5d5758661c, `app.py:2466-2484`, `model/feature_token_ops.py:3427-3446`). The invitation is not checked against `parentUUID`.
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.resendManageUserInvitation` (`src/app/services/user/user-http/user-http.service.ts:234-240`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-list/account-settings-manage-user-list.component.ts:147`; Android @ 86068bfeea, `callResendInvite` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:482`); iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/ManageUsers/ManageUsersViewModel.swift:81`.

**Request** (JSON): `parentUUID` and `userParentUUID` (the invitation's `tPri_UserParent` row, as `userParentUUID` in the [Invited user object](#invited-user-object)), both required. authpy sends them on to [resend\_account\_invitation](#post-actionresend_account_invitation).

**Response** `200`: the php-apis answer, passed on; on success "Invitation has been sent again to the user.".

**Errors:** `invalid params`; `unauthorised access`; the php-apis messages.

**Side effects:** as in [resend\_account\_invitation](#post-actionresend_account_invitation).

## POST /revoke-invitation

Cancels a site invitation.

* **Auth:** user token; [site admin check](#users-api) (authpy @ 5d5758661c, `app.py:2486-2506`, `model/feature_token_ops.py:3448-3466`). The invitation is not checked against `parentUUID`.
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.revokeManageUserInvitation` (`src/app/services/user/user-http/user-http.service.ts:243-249`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-list/account-settings-manage-user-list.component.ts:257`; Android @ 86068bfeea, `callRevokeInvite` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:514`); iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/ManageUsers/ManageUsersViewModel.swift:102`.

**Request** (JSON): as in [POST /resend-invitation](#post-resend-invitation); sent on to [revoke\_account\_invitation](#post-actionrevoke_account_invitation).

**Response** `200`: the php-apis answer, passed on; on success "Invitation has been revoked.".

**Errors:** `invalid params`; `unauthorised access`; the php-apis messages.

**Side effects:** as in [revoke\_account\_invitation](#post-actionrevoke_account_invitation).

## POST /user-token-jwt-device

Lists the devices a user is signed in on, with each device's block state at a site. The device screens call it.

* **Auth:** user token. The caller must be Snapfix staff (`fSnapfixWebAdminUser`), a live admin of any site, or a member of any multi-site. The target user is not checked against the caller's sites (authpy @ 5d5758661c, `app.py:1704-1720`, `model/feature_token_ops.py:675-742`).
* **Used by:** web\_app\_v2 @ 0989b8e685, `UserHttpService.getManageUserDeviceList` (`src/app/services/user/user-http/user-http.service.ts:188-196`), called from `src/app/pages/account-settings/account-settings-manage-users/account-settings-manage-user-access/user-devices/user-devices.component.ts:157`; Android @ 86068bfeea, `getLoggedInDevicesList` (`app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:590`); iOS @ aa31967ac8, `SnapFix/ParentSwither/Edit Parent/BottomSheet/BlockDeviceActionVC.swift:89`.

**Request** (JSON)

| Name         | Type   | Required | Rules                                                                  |
| ------------ | ------ | -------- | ---------------------------------------------------------------------- |
| `userUUID`   | string | yes      | The user whose devices are listed                                      |
| `parentUUID` | string | no       | The site whose block state is shown; default the caller's current site |

**Response** `200`: `data` is a list of [Device objects](#device-object), one per device that has a live token of the user and an Android or Apple record in `tPri_Device`. Only when none of the devices has such a record are they all listed, as `Unknown` with type `unknown` and last seen `0`.

**Errors:** `invalid params` when `userUUID` is missing; `unauthorised access`; `no data found` when the user has no device with a live token.

**Side effects:** none.

## POST ?action=delete\_group\_invitation

Cancels an open group invitation: marks it deleted.

* **Auth:** the user's Bearer token, checked by the dispatcher when `JWT_AUTH_ENABLED` is on; otherwise the shared Basic login ([Authentication](https://docs.snapfix.com/engineering-reference/api.md#authentication)) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The action checks no rights of the caller. The `uuid_tUser` in the body is only checked to exist, and the group in the body is never compared with the invitation's group.
* **Used by:** iOS (the group's users screen, ios @ aa31967ac8, `SnapFix/BusinessUsersEditVC.swift:1165`) and Android (android @ 86068bfeea, `fragment/BusinessUsersFragment.java:1562-1565`). Both send `POST` with a JSON body. apipy's `DELETE /group_invite` also forwards here (apipy @ 0e83c85e5a, `model/feature_php_api.py:100`), but no client calls that route: the Android function that did (`fragment/BusinessUsersFragment.java:1492-1507`) is never called.

**Request** (JSON)

| Name               | In   | Type   | Required | Rules                                                                                                                                 |
| ------------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tBusiness`   | body | string | yes      | Must not be empty: "invalid group". Not checked further                                                                               |
| `uuid_tUser`       | body | string | yes      | The actor; must exist and not be deleted: "invalid user"                                                                              |
| `uuid_groupInvite` | body | string | yes      | The invitation; must exist, not be deleted and not be processed: "invalid invitation" when empty, "invalid invitation data" otherwise |

**Response** `200`

```json
{
  "result": true,
  "message": "invitation deleted successfully",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and one of "invalid group", "invalid user", "invalid invitation" or "invalid invitation data" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:44552-44580`, `:44623-44629`). An empty body answers "Data cannot be blank!" (`html/api/snapfix/index.php:1010-1016`).

**Side effects:** sets `fDeleted` on the [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) row, updates `fModifiedTs` and `fServerTs`, and records the body's `uuid_tUser` in `uuid_tUser_ModifiedBy` (`class.functions.php:44586-44608`).

## POST ?action=group\_invitation

Invites a person to a group by email address or mobile number. If a live account already has that address or number, the account is added to the group at once.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The action checks neither that the caller is an admin of the group nor that the caller is a member. The inviter is the `uuid_tUser` in the body, which only has to exist.
* **Used by:**
  * iOS: the invite-by-contact screen (ios @ aa31967ac8, `SnapFix/AddUserToGroupVC/UserInviteContactVC.swift:161`). The add-user screen passes the same action with `isPythonAPI: true`, so its URL is the bare name `group_invitation` and the request cannot be sent (`SnapFix/AddUserToGroupVC/AddNewUserVC.swift:605`; `APIManagers/APIManager.swift:2287`).
  * Android: the invite sheet (android @ 86068bfeea, `bottomSheet/InviteUserBottomSheet.kt:144-147`).
  * apipy's `POST /group_invite` forwards here (apipy @ 0e83c85e5a, `model/feature_php_api.py:92`), but no client calls that route.

**Request** (JSON)

| Name             | In   | Type   | Required                                 | Rules                                                                                 |
| ---------------- | ---- | ------ | ---------------------------------------- | ------------------------------------------------------------------------------------- |
| `uuid_tBusiness` | body | string | yes                                      | The group; must exist and not be deleted: "invalid group"                             |
| `uuid_tUser`     | body | string | yes                                      | The inviter; must exist and not be deleted: "invalid user"                            |
| `origin`         | body | string | yes                                      | Where the invitation comes from; stored as `fOrigin`: "invalid origin"                |
| `email`          | body | string | `email`, or `country_code` with `mobile` | A valid email address: "invalid email". When both are sent, the email address is used |
| `country_code`   | body | string | with `mobile`                            | A leading `+` is removed                                                              |
| `mobile`         | body | string | with `country_code`                      | Checked by the mobile number validator, whose message is returned as is               |

**Response** `200`: `result` is `true` in every case below, and `data` is a [Group invitation object](#group-invitation-object) or a membership row.

| Case                                                           | `message`                                                                                                                                      | `data`                                         |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| No live account has the address or number                      | "An email invitation was sent. Once the user has registered, they will be added to your group", or the same with "An SMS invitation was sent." | The new invitation, with `invited` `true`      |
| An open invitation for that address or number and group exists | "This user already been invited for the mentioned group. Please resend if you want to notify the user again."                                  | The existing invitation                        |
| The account is already in the group                            | "This user already added to the group"                                                                                                         | The membership row                             |
| The account is not in the group                                | "User added to the group successfully"                                                                                                         | The new membership row, with `invited` `false` |

```json
{
  "result": true,
  "message": "An email invitation was sent. Once the user has registered, they will be added to your group",
  "data": {
    "uuid_groupInvite": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "uuid_tBusiness": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "fUsername": "jane@example.com",
    "fCountryCode": null,
    "fMobile": null,
    "staff_username": null,
    "invited_sms": 0,
    "invited_email": 1,
    "fCreatedTs": 1794387600000,
    "fModifiedTs": 1794387600000,
    "invited": true
  },
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and one of "invalid group", "invalid user", "invalid origin", "invalid email", "invalid invitee info" (neither an email address nor a mobile number), "duplicate invitee data found" (more than one live account has the address or number), or the mobile validator's message (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:44366-44533`). An empty body answers "Data cannot be blank!" (`html/api/snapfix/index.php:994-1000`).

**Side effects:**

* No live account: adds a [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) row with `invited_email` or `invited_sms` set to `1`, `fOrigin`, and the inviter as `uuid_tUser_CreatedBy`. It sends an email "Snapfix invitation by \<inviter's name>" from `noreply@snapfix.com` through AWS SES, or an SMS through the SMS helper (`class.functions.php:44535-44550`).
* A live account not yet in the group: adds a [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row with the member role, the permission flags set to `1`, and the inviter as creator, and adds one to the site's user count in Firebase. No message is sent.

## POST ?action=list\_group\_invitation

Lists a group's open invitations, newest first.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The group is not checked against the caller, so any signed-in user can list any group's invitees with their email addresses and mobile numbers.
* **Used by:** iOS (ios @ aa31967ac8, `SnapFix/BusinessUsersEditVC.swift:666`) and Android (android @ 86068bfeea, `fragment/BusinessUsersFragment.java:1356-1359`), on the group's users screen. apipy's `GET /group_invite/{uuid}` forwards here (apipy @ 0e83c85e5a, `model/feature_php_api.py:104`), but no client calls that route.

**Request** (JSON)

| Name             | In   | Type   | Required | Rules                                |
| ---------------- | ---- | ------ | -------- | ------------------------------------ |
| `uuid_tBusiness` | body | string | yes      | The group. Not checked for existence |

**Response** `200`: `data` is a list of [Group invitation objects](#group-invitation-object): the group's [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) rows that are neither deleted nor processed, by `fServerTs`, newest first.

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "uuid_groupInvite": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "uuid_tBusiness": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "fUsername": "jane@example.com",
      "fCountryCode": null,
      "fMobile": null,
      "staff_username": null,
      "invited_sms": 0,
      "invited_email": 2,
      "fCreatedTs": 1794387600000,
      "fModifiedTs": 1794387700000
    }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "invalid group" when `uuid_tBusiness` is empty, or "no invitations found!" when the group has none (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:44631-44645`). An empty body answers "Data cannot be blank!".

**Side effects:** none.

## POST ?action=read\_on\_call\_users

Lists the on-call users of one site. The iOS site list uses it; [read\_on\_call\_users\_v2](#post-actionread_on_call_users_v2) is the newer form.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The caller comes from the token and must be a live user. The site is not checked against the caller, so any signed-in user can list any site's on-call staff with their contact details.
* **Used by:** iOS (ios @ aa31967ac8, `SnapFix/BusinessListingVC.swift:462`), which sends form fields.

**Request** (form fields, not JSON)

| Name          | In   | Type   | Required | Rules                                                     |
| ------------- | ---- | ------ | -------- | --------------------------------------------------------- |
| `parent_uuid` | body | string | yes      | The site; must exist and not be deleted: "invalid parent" |

The action reads `$_POST` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1301-1307`), which a JSON body doesn't fill: a JSON body answers "Data cannot be blank!".

**Response** `200`: `data` lists the site's live, unblocked members whose site membership has `on_call` set, most recently changed first. Each item has `user_uuid`, `fUsername`, `fCountryCode`, `fMobile`, `fFirstName`, `fLastName`, `fName` and `fImage`.

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "user_uuid": "5f2c9a7e-1d3b-4c8e-9a60-2b7d4e1f8c33",
      "fUsername": "jane@example.com",
      "fCountryCode": "44",
      "fMobile": "7700900123",
      "fFirstName": "Jane",
      "fLastName": "Example",
      "fName": "Jane Example",
      "fImage": null
    }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "parent\_uuid must be mentioned in the request!", "invalid access!" (no user in the token), "invalid user", "invalid parent", or "no user is available for 'ON CALL'" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:35098-35132`).

**Side effects:** none.

## POST ?action=read\_on\_call\_users\_v2

Lists the on-call users of several sites at once, grouped by site. The apps' site switcher uses it.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The token must name a user, but the user is not looked up. The sites are not checked against the caller.
* **Used by:** iOS (ios @ aa31967ac8, `SnapFix/ParentSwither/SelectParentVC.swift:154`) and Android (android @ 86068bfeea, `viewModels/BusinessViewModel.java:963-968`, `bottomSheet/ParentSwitcherBottomSheet.java:317-324`). Both send `POST` with a JSON body.

**Request** (JSON)

| Name           | In   | Type             | Required | Rules                                                                                                                |
| -------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `parent_uuids` | body | array of strings | yes      | The sites; must be a non-empty list: "invalid params!". At least one must exist and not be deleted: "invalid parent" |

**Response** `200`: `data` is a list with one entry per UUID in the request, in the request's order. Each entry has `parnt_uuid` (spelled this way in the code) and `onCallUsers`, the site's on-call users with the same fields as in [read\_on\_call\_users](#post-actionread_on_call_users). A site with no on-call user, or one that does not exist, has an empty list.

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "parnt_uuid": "0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
      "onCallUsers": [
        {
          "user_uuid": "5f2c9a7e-1d3b-4c8e-9a60-2b7d4e1f8c33",
          "fUsername": "jane@example.com",
          "fCountryCode": "44",
          "fMobile": "7700900123",
          "fFirstName": "Jane",
          "fLastName": "Example",
          "fName": "Jane Example",
          "fImage": null
        }
      ]
    }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "invalid params!", "invalid access!" (no user in the token), "invalid parent" (none of the sites exists), or "no user is available for 'ON CALL'" when none of the sites has an on-call user (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:35134-35178`). An empty body answers "Data cannot be blank!" (`html/api/snapfix/index.php:986-992`).

**Side effects:** none.

## POST ?action=read\_pri\_user

Finds accounts by email address or mobile number, for the apps' add-user and profile flows. It is a [generic table read](https://docs.snapfix.com/engineering-reference/api.md#requests) on [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md), so it also reads users by UUID or by any other column.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The action checks no rights of the caller and limits the answer to no site or group. A request with no filter returns every account.
* **Used by:**
  * iOS: the add-user screen, the add-user guide, the settings and the profile (ios @ aa31967ac8, `SnapFix/AddUserToGroupVC/AddNewUserVC.swift:318`, `:345`; `SnapFix/AddUserGuidePopUp.swift:120`, `:143`; `SnapFix/MySettingsVC.swift:818`, `:833`; `SnapFix/New Profile/Profile/ViewModels/ProfileViewModel.swift:347`, `:362`).
  * Android: the profile, the add-user dialogs and the search-and-add sheet (android @ 86068bfeea, `activity/MyProfileActivity.kt:1585`; `dialog/AddEditUserDialog.java:753`, `:812`; `dialog/GuideAddUserDialog.java:270`; `bottomSheet/SearchAndAddNewUserBottomSheet.java:391`).
  * Both send `POST` with a JSON body.

**Request** (JSON)

| Name                      | In   | Type             | Required | Rules                                                         |
| ------------------------- | ---- | ---------------- | -------- | ------------------------------------------------------------- |
| `fUsername`               | body | string           | no       | The email address; the apps send it in lower case             |
| `fCountryCode`, `fMobile` | body | string           | no       | The mobile number; the apps send these instead of `fUsername` |
| `last_updated_ts`         | body | number           | no       | Defaults to `0`, which the apps also send                     |
| `uuid_tUser`              | body | string           | no       | Defaults to `-1`; never a filter on this table                |
| `uuids`                   | body | array of strings | no       | Read these users by UUID instead of filtering                 |

Any other key is a filter on the column of that name, as for every generic read. The dispatcher fills `uuid_tUser` and `last_updated_ts` when they are missing (php-apis @ 238ca4414e, `html/api/snapfix/index.php:3349-3355`), so "Invalid Request Params" does not occur here.

**Response** `200`: `data` is the matching `tPri_User` rows with every column, `fPassword` included. `current_max_id` comes with it.

```json
{
  "result": true,
  "current_max_id": 456,
  "message": "Values Found!",
  "data": [
    {
      "uuid": "5f2c9a7e-1d3b-4c8e-9a60-2b7d4e1f8c33",
      "fUsername": "jane@example.com",
      "fFirstName": "Jane",
      "fLastName": "Example",
      "fCountryCode": "44",
      "fMobile": "7700900123",
      "fPassword": "--disabled--",
      "fServerTs": 1794387600000
    }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "No Record found!" when nothing matches (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:1799-1841`, `:2737-2746`).

**Side effects:** none.

## POST ?action=read\_pri\_user\_business

Reads group memberships ([`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows): a [generic table read](https://docs.snapfix.com/engineering-reference/api.md#requests). The apps' add-user flows use it to find a user's membership of a group.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). No rights of the caller are checked.
* **Used by:** iOS (the add-user screen, ios @ aa31967ac8, `SnapFix/AddUserToGroupVC/AddNewUserVC.swift:398` through `APIManagers/APIManager.swift:1047-1050`) and Android (android @ 86068bfeea, `dialog/AddEditUserDialog.java:852`, `dialog/GuideAddUserDialog.java:339`). Both send `POST` with a JSON body.

**Request** (JSON)

| Name              | In   | Type             | Required                  | Rules                                                                                                                                                                                      |
| ----------------- | ---- | ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid_tUser`      | body | string           | yes (the key must be set) | Never a filter on this table, so the answer holds every member of the group, not just this user; the apps pick the user's row themselves (android `dialog/AddEditUserDialog.java:859-867`) |
| `last_updated_ts` | body | number           | yes (the key must be set) | Keeps rows changed from 5 seconds before it; the apps send `0`                                                                                                                             |
| `uuid_tBusiness`  | body | string           | no                        | The group                                                                                                                                                                                  |
| `uuids`           | body | array of strings | no                        | Read these memberships by UUID instead of filtering                                                                                                                                        |

Other keys filter as for every generic read. Deleted memberships are included unless the request filters on `fDeleted`.

**Response** `200`: `data` is the matching rows with every column, with `current_max_id` and "Values Found!", as in [read\_pri\_user](#post-actionread_pri_user).

**Errors:** `200` with `result` `false` and "Invalid Request Params" when `uuid_tUser` or `last_updated_ts` is not set, or "No Record found!" when nothing matches (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:1799-1841`; `html/api/snapfix/index.php:3549-3552`, which fills no defaults).

**Side effects:** none.

## POST ?action=read\_users

Lists the users of a site or of a group, with their full rows. The web admin app's user pickers use it.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The request can name any site or group, or none.
* **Used by:** webadmin\_angular, the users picker and the site's users dialog (webadmin\_angular @ db972390b8, `src/app/services/user/user.service.ts:30-33`, called from `src/app/components/users-select/users-select.component.ts:39` and `src/app/pages/account/components/business-users-modal/business-users-modal.component.ts:245`). It sends `POST` with `uuid_tParent`. No app calls it.

**Request** (JSON)

| Name             | In   | Type   | Required | Rules                                                                                                               |
| ---------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `uuid_tParent`   | body | string | no       | The site: the members of all its groups, deleted groups included. "invalid parent uuid" when the site has no groups |
| `uuid_tBusiness` | body | string | no       | A group, added to the site's groups                                                                                 |

With neither key, the action reads every membership row in the database and returns every user in one of them. Deleted memberships count in every case (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:3068-3107`). The read runs on the read-only database (`html/api/snapfix/index.php:3249-3252`).

**Response** `200`: `data` lists the users' `tPri_User` rows with every column, `fPassword` included. Each user is read on its own, and `current_max_id` is `-1`.

```json
{
  "result": true,
  "current_max_id": -1,
  "message": "Values Found!",
  "data": [
    {
      "uuid": "5f2c9a7e-1d3b-4c8e-9a60-2b7d4e1f8c33",
      "fUsername": "jane@example.com",
      "fFirstName": "Jane",
      "fLastName": "Example",
      "fCountryCode": "44",
      "fMobile": "7700900123",
      "fAddress": "Room 101",
      "fPassword": "--disabled--"
    }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "invalid parent uuid" when the site has no groups, or "No Record found!" when no membership matches or none of their users is found (`class.functions.php:3107-3109`, `:1799-1841`).

**Side effects:** none.

## POST ?action=read\_users\_v2

Reads the full rows of one or more users by UUID. The apps use it to fetch users that are missing from the device's database, and to refresh the signed-in user's own row, for example the language.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). Any account can be read: the answer is limited neither to the caller nor to users who share a group.
* **Used by:** iOS (ios @ aa31967ac8, `Managers/TaskManager.swift:2670`) and Android (android @ 86068bfeea, `network/ReadDataManager.java:761`, `network/ReadDataManagerKotlin.kt:960`, `utils/UserLanguageManager.kt:84`). Both send `POST` with a JSON body.

**Request** (JSON)

| Name         | In   | Type                       | Required | Rules                                                  |
| ------------ | ---- | -------------------------- | -------- | ------------------------------------------------------ |
| `uuid_tUser` | body | string or array of strings | yes      | One user UUID or a list: "invalid params" when missing |

**Response** `200`: `data` lists the [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) rows with every column, `fPassword` and the staff flag included. Deleted accounts are returned too. The read uses the read-write database (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:25735-25752`).

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "uuid": "5f2c9a7e-1d3b-4c8e-9a60-2b7d4e1f8c33",
      "fUsername": "jane@example.com",
      "fFirstName": "Jane",
      "fLastName": "Example",
      "fLanguage": "en",
      "fPassword": "--disabled--",
      "fDeleted": 0
    }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "invalid params", or "no data" when no row matches. An empty body answers "Data cannot be blank!" (`html/api/snapfix/index.php:1664-1672`).

**Side effects:** none.

## POST ?action=resend\_group\_invitation

Sends an open group invitation again: an SMS if the invitation went by SMS, otherwise an email. It raises the send count.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The action checks no rights of the caller, and never compares the invitation's group with `uuid_tBusiness`.
* **Used by:** iOS (ios @ aa31967ac8, `SnapFix/BusinessUsersEditVC.swift:1138`) and Android (android @ 86068bfeea, `fragment/BusinessUsersFragment.java:1458-1461`), on the group's users screen. apipy's `PUT /group_invite` forwards here (apipy @ 0e83c85e5a, `model/feature_php_api.py:96`), but no client calls that route: the Android function that did (`fragment/BusinessUsersFragment.java:1391-1406`) is never called.

**Request** (JSON): the same fields as [delete\_group\_invitation](#post-actiondelete_group_invitation). A non-empty `fDeleted` turns the call into a cancellation.

**Response** `200`

```json
{
  "result": true,
  "message": "An email invitation was resent. Once the user has registered, they will be added to your group",
  "serverTs": 1794387595000
}
```

For an SMS invitation the message starts "An SMS invitation was resent."

**Errors:** `200` with `result` `false` and the errors of [delete\_group\_invitation](#post-actiondelete_group_invitation), or "invalid params!" when the invitation has neither an SMS nor an email count (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:44552-44602`).

**Side effects:** adds one to `invited_sms` (when it is above 0) or else to `invited_email` on the [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) row, updates `fModifiedTs` and `fServerTs`, and records the body's `uuid_tUser` in `uuid_tUser_ModifiedBy`. `fOrigin` is not changed. Sends the SMS or the email to the stored address, as [group\_invitation](#post-actiongroup_invitation) does, with the actor's name as the inviter (`class.functions.php:44603-44620`).

## POST ?action=save\_pri\_log\_startappuser

Writes a start-app log row: which user opened which app version, from where.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The body names the user, and nothing compares it with the token.
* **Used by:**
  * iOS, on the splash screen after an IP lookup (ios @ aa31967ac8, `SnapFix/SplashScreen/SplashScreenVC.swift:261`, `APIManagers/APIManager.swift:1552-1576`).
  * Android (android @ 86068bfeea, `activity/BusinessListingActivity.java:3260`).
  * web\_payments, at sign-in (web\_payments @ 7c2c3ddffd, `src/app/services/user/user.service.ts:42-52`, from `src/app/pages/auth/auth.component.ts:55`).
  * All send `POST` with a JSON body.

**Request** (JSON)

| Name          | In   | Type   | Required | Rules                                                                        |
| ------------- | ---- | ------ | -------- | ---------------------------------------------------------------------------- |
| `user_uuid`   | body | string | yes      | The user the log is for                                                      |
| `app_version` | body | string | yes      | The app version; web\_payments sends `<version>_<origin>`                    |
| `ip_data`     | body | object | yes      | The IP lookup's answer, stored as JSON; must not be empty: "invalid IP Data" |

**Response** `200`

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

**Errors:** `200` with `result` `false` and "user\_uuid, app\_version must be mentioned in the request!" (the missing names), "invalid IP Data", or "Log Error : " followed by the database error (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:22658-22677`). An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (`html/api/snapfix/index.php:2079-2086`).

**Side effects:** adds a [`tPri_Log_StartAppUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_startappuser.md) row with `uuid_tUser` and `uuid_tUser_CreatedBy` set to `user_uuid`, `fAppVersion`, and `fIpData`.

## POST ?action=save\_pri\_new\_user\_v7

Creates accounts for users the apps made on the device: the upload of pending users in the apps' sync. Each user becomes a registered account with a password.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). No rights of the caller are checked, and nothing proves that the caller owns the email address or mobile number. The new account can sign in with the password in the request at once: authpy's login reads the newest hash and never reads `fRegistered` (authpy @ 5d5758661c, `model/feature_user_auth.py:144-148`).
* **Used by:** iOS (ios @ aa31967ac8, `Managers/TaskManager.swift:857`) and Android (android @ 86068bfeea, `data/repository/SyncRepository.kt:231-236`), in their sync. Both send `POST` with a JSON body.

**Request** (JSON)

| Name                                                                                                                                                   | In         | Type             | Required             | Rules                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_data`                                                                                                                                            | body       | array of objects | yes                  | One object per user: "invalid params" when it is not an array (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/cognito.functions.php:730-761`)                                                                                                                 |
| `fUsername`, `fCountryCode`, `fMobile`                                                                                                                 | per object | string           | yes (all three keys) | The keys must all be present, though they may be empty. The email address is used when not empty and must be valid ("Invalid Email Address!"). The mobile number is used when both parts are set and `fMobile` is above 0, and goes through the mobile validator |
| `fPassword`                                                                                                                                            | per object | string           | no                   | At least 6 characters ("Password should have minimum 6 alphanumberic characters!"). A random 8-digit number is used when it is missing                                                                                                                           |
| `new_user_uuid`                                                                                                                                        | per object | string           | no                   | The new user's UUID, chosen by the caller; generated when missing                                                                                                                                                                                                |
| `fFirstName`, `fLastName`, `fAddress`, `fNotes`, `fOrigin`, `fLogging`, `fRedDotAlert`, `fRegistered`, `uuid_tUser_CreatedBy`, `uuid_tUser_ModifiedBy` | per object | any              | no                   | Copied to the new row when sent                                                                                                                                                                                                                                  |

**Response** `200`: record counts only. The per-user list is commented out in the code, so a failed user is counted, not named, and its reason is not returned.

```json
{
  "result": true,
  "message": "Success",
  "total_record_count": 2,
  "inserted_record_count": 1,
  "updated_record_count": 0,
  "insert_failed_record_count": 1,
  "update_failed_record_count": 0,
  "serverTs": 1794387595000
}
```

**Errors:**

* `200` with `result` `false` and "invalid params" when `user_data` is not an array, or when one object has neither a usable email address nor a usable mobile number. That stops the request, but the users before that object are already created.
* These per-user failures only raise `insert_failed_record_count`: an object without all three contact keys, an invalid email address, a short password, the mobile validator's message, "Email already exists!" or "Mobile Number already exists!" (the duplicate checks include deleted accounts) (`cognito.functions.php:763-953`).
* An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (`html/api/snapfix/index.php:2694-2702`).

**Side effects:**

* One [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row per new user, with `fRegistered` `1` and `fDeleted` `0` unless sent otherwise, and the placeholder `--disabled--` in `fPassword` (`cognito.functions.php:828-863`).
* One [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) row with the password's hash and salt (`cognito.functions.php:865-885`).
* No email or SMS is sent: the send calls are commented out (`cognito.functions.php:938-945`).
* After the answer, the dispatcher runs the queue processor (`html/api/snapfix/index.php:2696`, `:4451-4480`).

## POST ?action=save\_pri\_user\_business\_v2

Saves group memberships: inserts new [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows and updates existing ones by UUID. The apps use it to upload membership changes; the web admin app uses it to save a group user.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). Nothing checks that the caller may manage the group or the user named in a row.
* **Used by:**
  * iOS (ios @ aa31967ac8, `Managers/TaskManager.swift:1085`) and Android (android @ 86068bfeea, `data/repository/SyncRepository.kt:246-260`), in their sync.
  * webadmin\_angular, the group users dialog (webadmin\_angular @ db972390b8, `src/app/services/group-users/group-users.service.ts:104-106`).
  * All send `POST` with a JSON body.

**Request** (JSON)

| Name               | In   | Type             | Required | Rules                                                                                                                                                                                                                                                                                                                          |
| ------------------ | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `insert_data`      | body | array of objects | yes      | One membership row per object: `uuid`, `uuid_tBusiness`, `uuid_tUser`, `uuid_tUserType`, the permission flags and any other column. Values are stored as sent                                                                                                                                                                  |
| `send_invite_data` | body | array of objects | no       | The apps and the web admin app send it (iOS `APIManagers/APIManager.swift:1934-1938`; android `data/repository/SyncRepository.kt:252-260`), but this action never reads it \[[ASK-276](https://github.com/snapfix/docs/blob/main/ASK.md#ask-276-should-save_pri_user_business_v2-still-send-the-invitations-the-apps-ask-for)] |

**Response** `200`: the saved and the refused row UUIDs.

```json
{
  "result": true,
  "message": "",
  "success_data": [
    "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70"
  ],
  "error_data": [],
  "serverTs": 1794387595000
}
```

Which path runs depends on `LEGACY_QUEUE_SUPPORT`, a server setting (php-apis @ 238ca4414e, `htmlphp/api/snapfix/config/constant_dev.php:12`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]:

* **On:** each row becomes a queue entry, and every row's UUID is in `success_data`. A row without `uuid` gets one.
* **Off:** rows are saved at once. A row without `uuid` is skipped. A row whose `uuid` exists is updated, and its UUID goes into `success_data` when the update works. A new row for a user and group that already have a membership row, even a deleted one, is not saved: `error_data` gets `{"old_uuid": ..., "user_business_data": [the existing rows]}`.

**Errors:** `200` with `result` `false` and "something went wrong" when the queue path gets no rows (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:4642-4690`). An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (`html/api/snapfix/index.php:3524-3532`).

**Side effects:**

* Queue path: one queue entry per row, written to the tables by the queue processor that the dispatcher runs after the answer (`html/api/snapfix/index.php:3526`, `:4451-4480`).
* Direct path: updates the named row with every column sent and sets `fServerTs` and `fModifiedTs`; or inserts the row, adds one to the group's user count, and sends the "new joinee" notice to the group's admins (`class.functions.php:4692-4768`).

## POST ?action=save\_pri\_user\_v7

Saves a user's profile: the columns the apps edit, such as the names, the address and the language. The web admin app saves its user edits through it too, deletions included.

* **Auth:** as in [delete\_group\_invitation](#post-actiondelete_group_invitation). The row is the one named by `user_uuid`, and nothing checks that it is the caller's own row or limits the columns. A `fPassword` sets that account's sign-in password.
* **Used by:**
  * iOS: the profile, the settings, and the language change (ios @ aa31967ac8, `Models/User.swift:563-582`, `:613`, from `SnapFix/LanguageChangeVC.swift:120`; `SnapFix/New Profile/Profile/ViewModels/ProfileViewModel.swift:330`; `SnapFix/MySettingsVC.swift:1544`).
  * Android: the profile, the language and the tooltip settings (android @ 86068bfeea, `activity/MyProfileActivity.kt:1987`, `utils/UserLanguageManager.kt:223`, `utils/SimonAiTooltipManager.kt:98`).
  * webadmin\_angular, the edit-user dialog (webadmin\_angular @ db972390b8, `src/app/services/user/user.service.ts:93-113`, from `src/app/pages/users/components/edit-user-modal/edit-user-modal.component.ts:41`).
  * All send `POST` with a JSON body.

**Request** (JSON)

| Name                          | In   | Type   | Required | Rules                                                                                                    |
| ----------------------------- | ---- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `user_uuid`                   | body | string | yes      | The account to change (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/cognito.functions.php:375-400`) |
| `fMobile` with `fCountryCode` | body | string | refused  | "You are not supposed to use this API to update your mobile number"                                      |
| `fUsername`                   | body | string | refused  | "You are not supposed to use this API to update your email"                                              |
| `fImage`                      | body | string | no       | A value that does not start with `http` is read as a base64 image, saved, and replaced with its URL      |
| `fDeleted`                    | body | number | no       | `1` on a live account deletes it, as described below                                                     |
| `fPassword`                   | body | string | no       | Stored as `--disabled--`; a value that does not start with `--` becomes the account's new password hash  |
| other keys                    | body | any    | no       | Written to the row as sent, for any column. `fFastLoginProcess` is dropped                               |

The refusals apply only when `user_uuid` is set. Without it the save adds a new account with a new UUID, any email address or mobile number not yet taken, and the password in `fPassword`, or `123456` when none is sent (`class.functions.php:3600-3637`).

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis); `result` is `false` when the 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,
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and one of the two refusals above, or "invalid email", "Email already exists!", "invalid countrycode", "invalid mobile", "Mobile Number already exists!" or the mobile validator's message (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:3421-3489`). An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (`html/api/snapfix/index.php:2678-2685`).

**Side effects:**

* Updates the [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row named by `user_uuid`, sets `fServerTs` and `fModifiedTs`, and writes a queue entry for the change. If no row has that UUID, a new row is added with it (`class.functions.php:3539-3599`).
* `fDeleted` `1` on a live account: the first name gets the prefix `DEL -`, the username becomes `del-$-$-$-<time>-$-$-$-<old username>` with the old phone number added, the phone number is cleared, and the caller from the token is recorded as the modifier (`class.functions.php:3550-3568`).
* A `fPassword` that does not start with `--` adds a [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) row, which authpy's login then uses (`class.functions.php:3640-3654`).
* Sends the "user updated" notice for the account (`class.functions.php:3657-3659`).

## POST ?action=proxy\_add\_user

Adds one new user to a site and to groups. authpy's `POST /add-user` calls it, and no client calls that route. php-apis checks the request, answers, and creates the user after the answer.

* **Auth:** the shared Basic login (`AUTH_USERNAME`) and no user token. The action is on the web dispatcher's no-token list, so the Cognito and JWT checks skip it, and the Basic check runs whether `JWT_AUTH_ENABLED` is on or off (php-apis @ 238ca4414e, `html/api/snapfix/web/index.php:441`, `:445-535`; [Basic logins](https://docs.snapfix.com/engineering-reference/api.md#basic-logins)) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The action checks no caller, site or role: it trusts `logged_in_user` in the body, which authpy fills from the caller's token after its own checks.
* **Used by:** authpy `/add-user` (authpy @ 5d5758661c, `model/feature_php_api.py:197-211`, from `model/feature_token_ops.py:3481`), which no client calls: Android's create-user sheet, the only caller, is created only in commented-out code (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/ParentAccountUserFragment.kt:309`).

**Request** (JSON): authpy sends the fields inside `data` (`html/api/snapfix/web/index.php:1087-1093`).

| Field                   | Required                                | Rules                                                                                                                                                                                                                                                         |
| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `logged_in_user`        | yes                                     | The caller; recorded as creator and inviter                                                                                                                                                                                                                   |
| `parentUUID`            | yes                                     | The site                                                                                                                                                                                                                                                      |
| `firstname`             | yes                                     |                                                                                                                                                                                                                                                               |
| `lastname`              | no                                      |                                                                                                                                                                                                                                                               |
| `fPassword`             | yes                                     | Checked for presence only; the new account's `fPassword` is `--disabled--` and it gets no hash (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:3671-3680`)                                                                             |
| `origin`                | yes                                     | Where the user is added from                                                                                                                                                                                                                                  |
| `email`                 | `email`, or `countrycode` with `mobile` |                                                                                                                                                                                                                                                               |
| `countrycode`, `mobile` | with each other                         |                                                                                                                                                                                                                                                               |
| `groups`                | yes                                     | A non-empty list of `{uuid, usertype}`. `usertype` is `1bfdbc8f-e625-4739-be10-83cb7f52b83f` (admin) or `f9696aba-a38b-4e98-b4aa-e45980d011f5` (user)                                                                                                         |
| `user_type`             | no                                      | The site role, `normal` when missing; `contractor` gets no invitation. Not checked against the caller's role \[[ASK-229](https://github.com/snapfix/docs/blob/main/ASK.md#ask-229-which-roles-may-add-users-to-a-site-and-who-may-make-someone-a-site-admin)] |

**Response** `200` when the request is valid and no live account has the email address or mobile number. The user is created after this answer.

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

**Errors:** `200` with `result` `false` and the missing-field message ("logged\_in\_user, parentUUID must be mentioned in the request!" and so on), "invalid parameters" (no email address and no mobile number), "invalid groups", "invalid group params" (an entry without `uuid` or `usertype`), "invalid group param" (another `usertype`), "user duplication found!" or "user already exists!" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7304-7359`).

**Side effects:** after the answer, only when `result` is `true` (`html/api/snapfix/web/index.php:2602-2622`; `webapp.functions.php:7889-8079`):

* Creates the [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row with `temp_password` and `verification_required` set, and `temp_password_required` set because `fPassword` is sent. A contractor gets `temp_password` `0`.
* Adds a [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row for each group through the core helper, which records a fixed account as creator. The groups are not checked against `parentUUID`.
* Sets the site membership ([`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md)) on `parentUUID` with a new invitation link in `fNotes`: a live row is updated without an invitation, a deleted row is restored, and otherwise a row is added. The role is set to `user_type` when it differs.
* Sends the invitation for a new or restored membership, unless the user is a contractor.

## POST ?action=proxy\_add\_user\_v2

Adds one user to a site and to groups. authpy's [`POST /add-user-v2`](#post-add-user-v2) calls it. php-apis checks the request, answers, and then runs the write of [proxy\_add\_users](#post-actionproxy_add_users) for the one user.

* **Auth:** as in [proxy\_add\_user](#post-actionproxy_add_user) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Used by:** authpy `/add-user-v2` (authpy @ 5d5758661c, `model/feature_php_api.py:213-219`, from `model/feature_token_ops.py:3501`).

**Request** (JSON, inside `data`): the fields of [proxy\_add\_user](#post-actionproxy_add_user) without `fPassword`, which is not read. `logged_in_user`, `parentUUID`, `firstname` and `origin` are required, and `groups` must be a non-empty list of `{uuid, usertype}` with one of the two role UUIDs (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7361-7404`). An existing account is not refused: it is added to the site and groups.

**Response** `200`, with the answer of [proxy\_add\_users](#post-actionproxy_add_users):

```json
{
  "result": true,
  "message": "Request to create users is accepted and will be processed shortly.",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and the missing-field message, "invalid parameters", "invalid groups", "invalid group params", "invalid group param", or "invalid account" when the site is not found or deleted (`webapp.functions.php:7428-7432`).

**Side effects:** as in [proxy\_add\_users](#post-actionproxy_add_users), for one user.

## POST ?action=proxy\_add\_userbusiness\_v2

Adds users to groups, each with a role. Clients call authpy's [`POST /add-user-groups-v2`](#post-add-user-groups-v2), which calls this action.

* **Auth:** as in [proxy\_add\_user](#post-actionproxy_add_user) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The action checks no caller and no group's site; authpy checks only the caller's rights on `parentUUID`, which it does not pass on.
* **Used by:** authpy `/add-user-groups-v2` (authpy @ 5d5758661c, `model/feature_php_api.py:185-189`, from `model/feature_token_ops.py:3788`).

**Request** (JSON, inside `data`)

| Field             | Required | Rules                                                                                                                   |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `login_user_uuid` | yes      | The caller; recorded as creator                                                                                         |
| `userGroups`      | yes      | A non-empty list of `{userUUID, groups}`, where `groups` is a list of `{uuid, usertype}` with one of the two role UUIDs |

**Response** `200`

```json
{
  "result": true,
  "message": "User Group(s) association created successfully",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "login\_user\_uuid must be mentioned in the request!", "invalid params" (no `userGroups`), "invalid group params", "invalid group param", or "user association already exists" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7209-7240`, `:8081-8100`). Every entry is checked before the first write. authpy answers success whatever this action returns.

**Side effects:** for each user and group in order, the web helper `addUserBusiness` (`webapp.functions.php:8081-8180`):

* A live [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row with the same role stops the loop with "user association already exists", so the groups after it are not written.
* A deleted row, or a live row with another role, is restored or changed to the role.
* Otherwise a row is added with onboarding status Active, `login_user_uuid` as creator, and `perJobViewAll`, `perJobCreateNew`, `perAccessDocuments` and `perAssignUser` set to `1`. The group's user count goes up by one.

## POST ?action=proxy\_add\_users

Accepts a bulk add of users to a site. authpy's [`POST /add-users`](#post-add-users) calls it. php-apis reads the list, checks it, answers that the request is accepted, and writes the users after the answer.

* **Auth:** as in [proxy\_add\_user](#post-actionproxy_add_user) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Used by:** authpy `/add-users` (authpy @ 5d5758661c, `model/feature_php_api.py:221-227`, from `model/feature_token_ops.py:3525`).

**Request** (JSON, inside `data`)

| Field            | Required | Rules                                                                                        |
| ---------------- | -------- | -------------------------------------------------------------------------------------------- |
| `logged_in_user` | yes      | The caller                                                                                   |
| `parentUUID`     | yes      | The site; must exist and not be deleted: "invalid account"                                   |
| `origin`         | yes      | Where the users are added from                                                               |
| `users`          | yes      | A URL. php-apis fetches it from the server and reads a JSON list of users. Any address works |

Each user in the list has `firstname`, an `email` or a `countrycode` and `mobile` pair, and optionally `lastname`, `groups` (a list of `{uuid, usertype}`) and `user_type`. The entries' groups and roles are not checked here.

**Response** `200` when the list is read and valid. The `metadata` the function returns is removed before the answer (`html/api/snapfix/web/index.php:2550-2553`).

```json
{
  "result": true,
  "message": "Request to create users is accepted and will be processed shortly.",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and:

* The missing-field message.
* "Failed to fetch data from the URL", or "Error decoding JSON: " followed by the decoder's message (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7406-7422`).
* "invalid account" when the site is not found or deleted.
* "For security reasons, bulk upload of users can only be carried out within an paid Snapfix account. Please contact <support@snapfix.com> to choose one of our payment options." when the site is not a paying customer, the list has more than one user, and the caller is not staff (`fSnapfixWebAdminUser`) (`webapp.functions.php:7433-7443`).
* "Error with user.firstname at index N" and "Error with user.email OR (user.countrycode and user.mobile) at index N", joined with ", " for the whole list. Nothing is written when any user fails (`webapp.functions.php:7446-7494`).

**Side effects:** after the answer, for each user in the list (`html/api/snapfix/web/index.php:2618`; `webapp.functions.php:7503-7753`):

* Uses the live account with the email address or mobile number, or creates a [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row (`addUserAlone`). A user that matches more than one live account is skipped.
* Adds a [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row for each group through the core helper. A live row is kept as it is, and the creator is a fixed account.
* Looks up the site of the user's groups with SQL built from the group UUIDs as sent. The first site found replaces `parentUUID` for the site membership, so the user can join another site.
* Sets the site membership ([`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md)) with the entry's `user_type`, unchecked: a live row is updated without an invitation, a deleted row is restored, and otherwise a row is added, with a new invitation link in `fNotes`.
* Sends an invitation to a new user, or the existing-user invitation to an existing one, for a new or restored membership. A contractor is not invited.

## POST ?action=proxy\_manage\_userbusiness

Adds a user to groups and removes the user from groups, in one call. authpy's [`POST /manage-user-groups`](#post-manage-user-groups) calls it.

* **Auth:** as in [proxy\_add\_user](#post-actionproxy_add_user) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The groups are not checked against `parentUUID`.
* **Used by:** authpy `/manage-user-groups` (authpy @ 5d5758661c, `model/feature_php_api.py:191-195`, from `model/feature_token_ops.py:3814`).

**Request** (JSON, inside `data`)

| Field             | Required                          | Rules                                                       |
| ----------------- | --------------------------------- | ----------------------------------------------------------- |
| `login_user_uuid` | yes                               | The caller; recorded as creator and modifier                |
| `userUUID`        | yes                               | The user                                                    |
| `parentUUID`      | yes                               | The site; required, but not used                            |
| `groupsToAdd`     | `groupsToAdd` or `groupsToRemove` | A list of `{uuid, usertype}` with one of the two role UUIDs |
| `groupsToRemove`  | `groupsToAdd` or `groupsToRemove` | A list of group UUIDs                                       |

**Response** `200` with a message that counts the changes: "User added to N group(s) and removed from M group(s).", "User added to N group(s)." or "User removed from M group(s)." (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7290-7297`). M counts the groups named, whether or not the user had a membership there.

```json
{
  "result": true,
  "message": "User added to 1 group(s) and removed from 1 group(s).",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and the missing-field message, "invalid params" (neither list), "invalid group params", "invalid group param", "user association already exists", or "user neither added to group(s) not removed from group(s)" (`webapp.functions.php:7242-7302`).

**Side effects:**

* Each group to add goes through the web helper, as in [proxy\_add\_userbusiness\_v2](#post-actionproxy_add_userbusiness_v2).
* Each group to remove: sets `fDeleted` on the user's live [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows in it, with the note "Parent Admin () removed this from new user management section".

## POST ?action=resend\_account\_invitation

Sends a site invitation again. authpy's [`POST /resend-invitation`](#post-resend-invitation) calls it.

* **Auth:** as in [proxy\_add\_user](#post-actionproxy_add_user) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The action does not check that `userParentUUID` belongs to the site whose rights authpy checked.
* **Used by:** authpy `/resend-invitation` (authpy @ 5d5758661c, `model/feature_php_api.py:229-235`, from `model/feature_token_ops.py:3442`).

**Request** (JSON, inside `data`)

| Field            | Required | Rules                                                           |
| ---------------- | -------- | --------------------------------------------------------------- |
| `logged_in_user` | yes      | The caller; recorded as the membership's modifier               |
| `userParentUUID` | yes      | The site membership to invite again. Deleted rows are found too |
| `parentUUID`     | no       | authpy sends it; the action does not read it                    |

**Response** `200`

```json
{
  "result": true,
  "message": "Invitation has been sent again to the user.",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and the missing-field message, "invitation not found!" when no membership row has that UUID, "invitation info not found" when the user has no live invitation link, or "invitation info not found!" when no link was made by the membership's creator, and the creator is not `admin` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7841-7872`).

**Side effects:** sends the invitation again with the link found (`sendInvitationV2`), adds one to `invitation_count` in [`dynamiclink_user`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_user.md), and updates the membership's `fModifiedTs`, `fServerTs` and modifier (`webapp.functions.php:7873-7887`).

## POST ?action=revoke\_account\_invitation

Cancels a site invitation or membership. authpy's [`POST /revoke-invitation`](#post-revoke-invitation) calls it.

* **Auth:** as in [proxy\_add\_user](#post-actionproxy_add_user) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The membership is found by `userParentUUID` alone, in any site.
* **Used by:** authpy `/revoke-invitation` (authpy @ 5d5758661c, `model/feature_php_api.py:237-243`, from `model/feature_token_ops.py:3463`).

**Request** (JSON, inside `data`): `logged_in_user` and `userParentUUID`, both required, as in [resend\_account\_invitation](#post-actionresend_account_invitation).

**Response** `200`

```json
{
  "result": true,
  "message": "Invitation has been revoked.",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and the missing-field message, or "invitation info not found!" when no live membership row has that UUID (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:7756-7770`).

**Side effects** (`webapp.functions.php:7767-7826`):

* Sets `fDeleted` on the [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row and on the user's live [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows in that site's groups.
* If the user then has no live group or site membership anywhere, deletes the [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row: `fDeleted` is set, the first name gets the prefix `DEL -`, the username becomes `del-$-$-$-<time>` followed by the old username, and the phone number is cleared.

## Site user object

A user of a site, from [GET /v1/app/parents/{uuid}/users](#get-v1appparentsuuidusers) (`ParentUsersResource`).

| Field                           | Type                      | Meaning                                                                           |
| ------------------------------- | ------------------------- | --------------------------------------------------------------------------------- |
| `uuid`                          | string                    | The user's ID                                                                     |
| `username`                      | string                    | Sign-in name, usually an email address                                            |
| `name`, `firstname`, `lastname` | string or null            | Names                                                                             |
| `countryCode`, `mobile`         | number or string, or null | Mobile number                                                                     |
| `userType`                      | string                    | `Admin` when the user's site row has the type `admin`, otherwise `User`           |
| `image`                         | string or null            | Photo URL                                                                         |
| `tempUser`                      | integer                   | `1` when the user has a temporary password and has never signed in, otherwise `0` |

## Group member object

A user's membership of one group, from [add-relation](#post-v1appuseradd-relationitem_uuid) and [update-relation](#put-v1appuseruser_uuidupdate-relationitem_uuid) (`UserAssetBusinessResource`).

| Field                                                                                                     | Type           | Meaning                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                                                                    | string         | The user's ID                                                                                                                                                  |
| `isSystem`                                                                                                | boolean        | Whether the user is a system user                                                                                                                              |
| `relationUuid`                                                                                            | string         | The [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) row                                                   |
| `name`, `firstname`, `lastname`, `address`, `staffUsername`, `image`, `username`, `countryCode`, `mobile` | string or null | The user's details \[[ASK-72](https://github.com/snapfix/docs/blob/main/ASK.md#ask-72-should-every-member-get-the-other-members-and-invitees-contact-details)] |
| `relationDeleted`                                                                                         | integer        | `1` when the membership is deleted                                                                                                                             |
| `active`                                                                                                  | integer        | The membership's `fActive`                                                                                                                                     |
| `role`                                                                                                    | string         | `Admin` or `User`                                                                                                                                              |
| `user_type`                                                                                               | string         | Always `normal`: the user row it is read from has no such column                                                                                               |
| `onboard`                                                                                                 | string         | `Active` or `Inactive`                                                                                                                                         |
| `notificationDisabled`                                                                                    | integer        | `1` when the user muted the group                                                                                                                              |
| `tempUser`                                                                                                | integer        | As in the [Site user object](#site-user-object)                                                                                                                |
| `permissions`                                                                                             | object         | One boolean flag per key of the `Permission` enum, as in the [update-relation](#put-v1appuseruser_uuidupdate-relationitem_uuid) request                        |

Staff callers of the admin API also get `createdTs`, `createdBy`, `modifiedTs` and `modifiedBy`.

## Staff username object

A staff login of a site, from [GET /v1/app/staff-username](#get-v1appstaff-username) (`StaffUsernameResource`, table [`staff_username`](https://docs.snapfix.com/engineering-reference/db/tables/staff_username.md)).

| Field                                    | Type           | Meaning                                |
| ---------------------------------------- | -------------- | -------------------------------------- |
| `userUuid`                               | string         | The staff user's ID                    |
| `staffUsername`                          | string         | The staff username                     |
| `name`, `firstname`, `lastname`, `image` | string or null | The user's details                     |
| `createdTs`, `modifiedTs`                | integer        | Times in ms                            |
| `requestPasswordReset`                   | integer        | Whether a password reset was asked for |
| `requestTs`                              | string or null | When it was asked for                  |

## Invitation object

A pending group invitation, from [invite-resend](#put-v1appuserinvite_idinvite-resenditem_uuid) (`UserInviteResource`, table [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md)).

| Field                   | Type            | Meaning                                                |
| ----------------------- | --------------- | ------------------------------------------------------ |
| `uuid`                  | string          | The invitation's ID                                    |
| `countryCode`, `mobile` | string or null  | The invitee's number, for SMS and WhatsApp invitations |
| `username`              | string or null  | The invitee's email address, for email invitations     |
| `invitedEmail`          | integer or null | Emails sent                                            |
| `invitedSms`            | integer or null | SMS sent                                               |

## On-call list object

One site's on-call users, from [POST /v1/app/user/on-call](#post-v1appuseron-call) (`OnCallUsersResource`).

| Field         | Type   | Meaning                                                                                                                                                 |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`  | string | The site, as sent                                                                                                                                       |
| `onCallUsers` | array  | [User objects](https://docs.snapfix.com/engineering-reference/api/account.md#user-object), with `userType` always `User` and `userParentDeleted` `null` |

## Site user object (authpy)

A user of a site, from [POST /parent-users](#post-parent-users) and [POST /parent-users-v2](#post-parent-users-v2).

| Field                              | Type    | Meaning                                                                               |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `uuid_tUser`                       | string  | The user's ID                                                                         |
| `fUsername`                        | string  | Sign-in name, usually an email address                                                |
| `fFirstName`, `fLastName`, `fName` | string  | Names                                                                                 |
| `fImage`                           | string  | Photo URL                                                                             |
| `fCountryCode`, `fMobile`          | string  | Mobile number                                                                         |
| `user_type`                        | string  | The type of the user's site row: `admin` or `normal`; `normal` when the user has none |
| `blocked`                          | integer | `1` when any of the user's rows on the site is blocked                                |
| `last_activity_ts`                 | integer | Always `0`                                                                            |

## Invited user object

A pending site invitation, from [POST /parent-users-temporary](#post-parent-users-temporary).

| Field                                                                                | Type    | Meaning                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userParentUUID`                                                                     | string  | The invitation's [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row, used by [POST /resend-invitation](#post-resend-invitation) and [POST /revoke-invitation](#post-revoke-invitation) |
| `userUUID`                                                                           | string  | The invitee                                                                                                                                                                                                                              |
| `invitedAt`                                                                          | integer | When the row was made, in ms                                                                                                                                                                                                             |
| `invitedBy`                                                                          | string  | Who made it                                                                                                                                                                                                                              |
| `lastInvitedAt`                                                                      | integer | When the row last changed, in ms                                                                                                                                                                                                         |
| `invitationLink`                                                                     | string  | The link stored in the row's `fNotes`. Code that would build a fresh link is commented out (`model/feature_token_ops.py:3204`)                                                                                                           |
| `fFirstName`, `fLastName`, `fName`, `fImage`, `fUsername`, `fCountryCode`, `fMobile` | string  | As in the [Site user object (authpy)](#site-user-object-authpy)                                                                                                                                                                          |

## Site group object

A group of a site, from [POST /parent-all-businesses](#post-parent-all-businesses), [POST /parent-other-businesses](#post-parent-other-businesses) and [POST /parent-user-businesses](#post-parent-user-businesses). Each route returns the fields its section names.

| Field                | Type            | Meaning                                                                                                                                                                           |
| -------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tBusiness`     | string          | The group's ID                                                                                                                                                                    |
| `fName`, `fImage`    | string          | The group's name and image                                                                                                                                                        |
| `enum_BusinessType`  | string          | The group type                                                                                                                                                                    |
| `user_role`          | string or null  | The user's role in the group, `Admin` or `User`; for a multi-site user with no membership, `User`                                                                                 |
| `uuid_tUserBusiness` | string or null  | The user's newest membership row; `null` when there is none or it is deleted                                                                                                      |
| `uuid_tUserType`     | string or null  | The role of that row                                                                                                                                                              |
| `uuid_tUser`         | string or null  | The user, when there is a membership row                                                                                                                                          |
| `business_disabled`  | integer or null | `1` when the user's newest membership of the group is deleted, `0` when it is live, `null` when there is none (`0` for a multi-site user); it says nothing about the group itself |

## Device object

A device a user is signed in on, from [POST /user-token-jwt-device](#post-user-token-jwt-device).

| Field                 | Type    | Meaning                                                                                                                                                       |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `device_id`           | string  | The device's ID, as sent to [POST /block-devices-v2](#post-block-devices-v2)                                                                                  |
| `device_name`         | string  | Make and model, or `Unknown`                                                                                                                                  |
| `device_type`         | string  | `android`, `apple` or `ios`, or `unknown`                                                                                                                     |
| `device_last_seen_ts` | integer | When the device was last seen, in ms, or `0`                                                                                                                  |
| `blocked`             | integer | `1` when the site's newest [`tPri_ParentDevice`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentdevice.md) row for the device is blocked |

## Group invitation object

An open invitation to join a group: a [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) row, from [group\_invitation](#post-actiongroup_invitation) and [list\_group\_invitation](#post-actionlist_group_invitation).

| Field                          | Type           | Meaning                                                                                           |
| ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------- |
| `uuid_groupInvite`             | string         | The invitation's UUID                                                                             |
| `uuid_tBusiness`               | string         | The group                                                                                         |
| `fUsername`                    | string or null | The invitee's email address, for an email invitation                                              |
| `fCountryCode`, `fMobile`      | string or null | The invitee's mobile number, for an SMS invitation                                                |
| `staff_username`               | string or null | A staff username, when set                                                                        |
| `invited_sms`, `invited_email` | number         | How many times the invitation went by SMS or by email                                             |
| `fCreatedTs`, `fModifiedTs`    | number         | When the invitation was made and last changed (ms)                                                |
| `invited`                      | boolean        | Only in the [group\_invitation](#post-actiongroup_invitation) answer: `true` for a new invitation |


---

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