> 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/how-the-apps-work/screens/console/users.md).

# Users

{% 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)). Platforms: web, iOS and Android. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/console/users.md).
{% endhint %}

Admins invite people to the site and manage their groups and roles, site permissions, site admin role and devices; the apps do a smaller part of this.

![Users](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-8ff2e7f641851870d146fce7cef8bb9de41d6029%2Fusers.png?alt=media)

* **Where:** web `/account/:id/manage-users` (Site Console, tab "Users"; the tab always shows). iOS: side menu "Site Administration" > "Users" (site admins only), which opens the second page of the site console; every member also reaches it from the "Users" tab of [Site details](https://docs.snapfix.com/how-the-apps-work/screens/console/site-details.md). Android: side menu "Site Administration" > "Users" (site admins), which opens the second tab of the site console; the "Users" tab of Site Details shows to every member.
* **Who:** web: role "Admin" and group admins (`authAdminGuard`). Group admins see the active list and can add users, but the groups, permissions and devices are read-only for them, and they get no "Invited" tab, no site admin box and no "Remove User". iOS and Android: every member sees the active list; only site admins get the add button, the Invited tab and the user actions \[[ASK-130](https://github.com/snapfix/docs/blob/main/ASK.md#ask-130-should-members-who-are-not-admins-see-the-sites-user-list-in-the-apps)].
* **Feature:** [Site users](https://docs.snapfix.com/product/features/console/site-users.md)

Most calls on this screen belong to the [Users API](https://docs.snapfix.com/engineering-reference/api/users.md); the site permission calls are in the [Console API](https://docs.snapfix.com/engineering-reference/api/console.md). Multi-site users also show in this list; their multi-site role is changed on [Users (multi-site)](https://docs.snapfix.com/how-the-apps-work/screens/console/multi-site-users.md).

## Layout

### Web

1. **Left column (one third).** Tabs "Active" and "Invited" (hidden for group admins); the open tab shows its count, as "Active (N)". A "Search users" field and a "+" button (title "Add New Users", role "Admin" and group admins). The list: photo, name, and the badges "ADMIN", "CONTRACTOR" and "MULTI-SITE" where they apply. It loads 50 users at a time as you scroll. The selected row is highlighted. A selected invited row shows a resend icon (title "Resend") once the last invite is 72 hours old.
2. **Right column, header (two thirds; role "Admin" and group admins).** Photo, name, the sign-in email and phone, and an activity line: "Last activity" with a date, "No activity yet", or, for an invited user, "Invited on" with the date and "Last invited on" when re-invited. Then the "Make a Site Admin" box, and at the right "Remove User", or "Copy invite link" and "Revoke invite" for an invited user. None of these show for the signed-in user's own row.
3. **Groups card.** "Groups", a search field "Search Groups", "Select All", and one row per task group of the site with a checkbox and a role menu ("Admin" or "User"). "Cancel" and "Save" are disabled until something changes. The card lists every live task group of the site (a group admin sees only the groups they run), so it can be much longer than the user's own groups.
4. **Access card.** Tabs "Site Permissions" and "Devices". The card is not shown for a contractor.

### iOS

1. **Tabs.** "Active" and "Invited" (site admins only), a search field, and a "+" button (site admins only).
2. **List.** Photo and name for each user. Site admins tap a row to open the user sheet; for everyone else the rows do nothing.

### Android

1. **Header.** Chips for active and invited users (site admins only); everyone else sees "Users in this account". A search field and an add button (site admins only).
2. **List.** Photo, name, and the email or phone when the site shows contact details. A pull-to-refresh list with paging. Rows open the user sheet for site admins only.

## Inputs

### Site permissions (web)

The heading is "Allow this user to:". Each switch saves at once and sends all five flags. Each has a help popover:

| Switch                                | Help text                                                                                                                                                                                          |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Create New Group"                    | "Allow this user to create new Groups within sites they have access to."                                                                                                                           |
| "Manage Tags"                         | "Allow this user to add and edit Tags in the site."                                                                                                                                                |
| "Edit Tag Folders"                    | "Allow this user to edit Tag Folders in the site."                                                                                                                                                 |
| "Create \| Edit \| Delete Checklists" | "Allow this user to create, edit, and manage checklists using the group setting."                                                                                                                  |
| "Enable AI Auto-Assign"               | "When enabled, and if AI-Assisted Field Suggestions is active at the site level, Snapfix AI will automatically assign tasks created by this user." Shown only when the site has AI suggestions on. |

The switches are disabled for group admins and for a user who is a site admin (a site admin has them all).

### Groups and roles (web)

| Field        | Type                    | Required         | Default                | Rules and messages                               |
| ------------ | ----------------------- | ---------------- | ---------------------- | ------------------------------------------------ |
| Group search | Text                    | No               | Empty                  | Filters the card's groups on the page            |
| Group        | Checkbox per task group | No               | Current membership     | Tick to add, untick to remove; saved with "Save" |
| Role         | Menu: "Admin" or "User" | Yes, once ticked | "User" for a new group | Saved with "Save"                                |

### Add New Users (web)

The dialog says "Add up to 10 users at a time.", "Enter the new user details below, including their groups and click '+' to add them." and "Note that at least one contact type is required."

| Field             | Type                                                     | Required               | Default | Rules and messages                                                                                                                                                                                                                              |
| ----------------- | -------------------------------------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| First Name        | Text                                                     | Yes                    | Empty   | Up to 30 characters. "Please enter a first name"; longer: "Your input exceeds the maximum allowed length of 30 characters"                                                                                                                      |
| Last Name         | Text                                                     | Yes                    | Empty   | Up to 30 characters. "Please enter a last name"                                                                                                                                                                                                 |
| Registration Type | "Email" or "Phone Number"                                | Yes                    | "Email" | Changing it clears the email and phone                                                                                                                                                                                                          |
| Email             | Text                                                     | When the type is email | Empty   | Up to 70 characters; placeholder "Enter your email". "Please enter an email address", "Please enter a valid email address". A repeat in the list: "The email address {email} is already assigned to another user. Please enter a unique email." |
| Phone number      | International phone field                                | When the type is phone | Empty   | "Please enter a phone number", "Invalid phone number". A repeat in the list: "The mobile number {number} is already assigned to another user. Please enter a unique mobile number."                                                             |
| Groups            | "Select Groups" opens a group list with a role per group | Yes                    | None    | "Please select a group"                                                                                                                                                                                                                         |
| Contractor        | Checkbox                                                 | No                     | Off     | Email users only; a contractor is added with the user type `contractor`                                                                                                                                                                         |

"Save Users", under the form, stays disabled until the entry is valid, then adds it to "Added users"; the list holds 10, after which "You have reached the maximum number of users." shows. Duplicate checks look only at the list, not at the site's users. "Add Users", at the bottom of the dialog, sends the list and stays disabled while it is empty; "Please complete the form and click the plus (+) button" shows when an entry was filled in but not added.

### Upload Users (web)

* **File:** one ".XLS or .XLSX" file based on the "Download Template" file; the first sheet is read, with the columns "First Name", "Last Name", "Email", "Country Code" and "Cell Phone (Mobile)". A file without them shows "The uploaded file does not contain the required fields for the upload process. Please provide a file based on the simple template."
* **Review:** each row needs a first name, a last name and an email or phone; repeats in the file are flagged. "Confirm Upload" stays disabled until the rows are valid, with "Please review and correct the highlighted errors before submitting."
* Uploaded rows get no groups and are never contractors \[[ASK-128](https://github.com/snapfix/docs/blob/main/ASK.md#ask-128-should-users-added-from-a-spreadsheet-get-no-groups)]. The 10-user limit is not applied to a file \[[ASK-129](https://github.com/snapfix/docs/blob/main/ASK.md#ask-129-should-the-spreadsheet-upload-keep-the-10-user-limit)].

## Actions

### Web

| Action                   | Who                        | What happens                                                                                                                                                                                                                                                                                                                                                                      | API                                                                                                                                                                                                                                                           |
| ------------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Load the list            | Role "Admin", group admins | Active users, or invited users on the "Invited" tab, 50 at a time with the search text.                                                                                                                                                                                                                                                                                           | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                                                                      |
| Open a user              | Role "Admin", group admins | Shows the header, the groups card, and the site permissions or devices.                                                                                                                                                                                                                                                                                                           | [`GET /user/{userUUID}/site/{siteUUID}/permission`](https://docs.snapfix.com/engineering-reference/api/console.md#get-useruseruuidsitesiteuuidpermission); groups and devices in the [Users API](https://docs.snapfix.com/engineering-reference/api/users.md) |
| Make a Site Admin        | Role "Admin"               | Ticking or unticking saves the user's role at once, with no confirmation \[[ASK-136](https://github.com/snapfix/docs/blob/main/ASK.md#ask-136-should-make-a-site-admin-ask-before-saving)]; making someone admin turns on all five permissions. The list and the permissions reload. Not offered for contractors, invited users or the signed-in user; disabled for group admins. | [`PUT /user/{userUUID}/site/{siteUUID}/permission`](https://docs.snapfix.com/engineering-reference/api/console.md#put-useruseruuidsitesiteuuidpermission)                                                                                                     |
| Change a site permission | Role "Admin"               | Saves at once.                                                                                                                                                                                                                                                                                                                                                                    | [`PUT /user/{userUUID}/site/{siteUUID}/permission`](https://docs.snapfix.com/engineering-reference/api/console.md#put-useruseruuidsitesiteuuidpermission)                                                                                                     |
| Save groups              | Role "Admin"               | Adds the ticked groups, removes the unticked ones and changes roles. A failure shows the API's message, but the card then reloads as if the save had worked. "Cancel" restores the card.                                                                                                                                                                                          | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md); role changes in the [Groups API](https://docs.snapfix.com/engineering-reference/api/groups.md)                                                                                      |
| Add New Users            | Role "Admin", group admins | "Add Users" uploads the list as a JSON file, then sends the invites, and shows the success view. When every added user is a contractor, the dialog closes and the "Active" tab opens instead.                                                                                                                                                                                     | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                                                                      |
| Remove User              | Role "Admin"               | Asks "Remove this user from the site?", then removes the user from every group of the site and from the site.                                                                                                                                                                                                                                                                     | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                                                                      |
| Resend invite            | Role "Admin"               | The resend icon on the selected invited row, 72 hours after the last invite.                                                                                                                                                                                                                                                                                                      | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                                                                      |
| Revoke invite            | Role "Admin"               | Asks "Revoke this user's invite?" with "Revoke".                                                                                                                                                                                                                                                                                                                                  | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                                                                      |
| Copy invite link         | Role "Admin"               | Copies the invite link and shows "URL copied to clipboard".                                                                                                                                                                                                                                                                                                                       | None                                                                                                                                                                                                                                                          |
| Block or unblock devices | Role "Admin"               | Tick devices, then "Block Device(s)" (disabled with none ticked) asks "Block the selected device?"; "Unblock" on a blocked device asks "Unblock the selected device?".                                                                                                                                                                                                            | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                                                                      |

Failed saves on this page show the API's message in an alert; a failed list load shows nothing.

### iOS and Android

| Action                     | Who          | What happens                                                                                                                                                                                                             | API                                                                                                                                                                                                                 |
| -------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Load the list              | Every member | Active users; invited users for site admins only. Search filters the loaded rows on the device.                                                                                                                          | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                            |
| Add a user                 | Site admins  | "Add a New User": by phone number, by email, or by QR code. Phone and email open a form, then groups and roles, then a success sheet. QR asks for groups and roles, then shows a one-time code for the new user to scan. | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md); QR: [`POST /v1/app/generate-dynamic-link`](https://docs.snapfix.com/engineering-reference/api/account.md#post-v1appgenerate-dynamic-link) |
| Block or unblock a user    | Site admins  | "Block the user from this account?" (or the unblock text). Not offered for the signed-in user.                                                                                                                           | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                            |
| Block devices              | Site admins  | Lists the user's devices and blocks or unblocks the chosen ones.                                                                                                                                                         | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                            |
| Manage Groups and Roles    | Site admins  | A sheet with the task groups: tick to add or remove, a role per group, then save. A failure shows a toast on iOS and nothing on Android.                                                                                 | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                            |
| Resend or revoke an invite | Site admins  | Resend shows 72 hours after the last invite; Android asks before revoking.                                                                                                                                               | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                            |

Neither app offers "Remove user from the account" or "Reset Password": both are in the code but always hidden, and Android's reset sheet would send nothing \[[ASK-138](https://github.com/snapfix/docs/blob/main/ASK.md#ask-138-should-the-apps-let-site-admins-remove-users-and-reset-their-passwords)].

## States

* **Loading:** web: spinners in the list, the header and each card. iOS and Android show the list when it arrives; Android shows "Loading...".
* **Empty:** web: "No data available" in the list and in the groups card; the Devices tab says "No devices listed, or the user has not logged on since Snapfix device management implemented." Android: "No data found".
* **Error:** web: failed saves show the API's message; failed list loads show nothing and the list stays as it was. Apps: see the group sheet above.
* **No permission:** web: group admins see the list, the groups card and the access card read-only, without the controls named under **Who**; other members never reach the route. Apps: non-admins see the active list with no add button, no tabs and no user sheet.
* **Offline (mobile):** the user actions need a connection; Android checks it first and shows its connection alert.

## Dialogs and sheets

* **Add New Users (web):** an 820-pixel dialog with "Upload Users", the form above with "Select Groups" and "Save Users", the "Added users" list, and "Add Users" at the bottom. Sub-views: "Select Groups" (task groups only, with "Back"), a review view that edits one added user, and the success view: "New user invited to this site!" (or "New users invited to this site!"), "An invite has been sent by SMS or email to the user you just added." (or the plural), "Please ask them to make sure to check their inbox (and Spam/Junk folder) to verify their profile.", "We look forward to having them on Snapfix!", "Happy Snapfixing!" and "Done".
* **Upload Users (web):** a 750-pixel dialog with the template text, "Choose a file", "Cancel" and "Save", then the review ([Inputs](#upload-users-web)).
* **Remove User (web):** "Remove User", "Remove this user from the site?", buttons "Cancel" and "Remove User".
* **Revoke invite (web):** "Revoke invite", "Revoke this user's invite?", buttons "Cancel" and "Revoke".
* **Block device (web):** "Block Device", "Block the selected device?", "Block"; unblock uses "Unblock Device" and "Unblock the selected device?".
* **User sheet (iOS):** "Block this User", "Block this User’s Devices", "Manage Groups and Roles", and "Please go to your Snapfix Web for more user management features."; for an invited user, "Resend invite" and "Revoke invite".
* **User sheet (Android):** "Block this User" or "Unblock this User", "Manage Groups and Roles" and the devices option; for an invited user, "Resend invite", "Revoke invite" (with a confirmation) and "Manage Groups and Roles".
* **Add a New User (iOS, Android):** the sheet with its three options, the form, groups and roles, then the success sheet.

## Platform differences

| Topic                               | Web                                             | iOS                                                                                                                                                       | Android                                                                                                                                                   |
| ----------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Who sees the list                   | Role "Admin" and group admins                   | Every member \[[ASK-130](https://github.com/snapfix/docs/blob/main/ASK.md#ask-130-should-members-who-are-not-admins-see-the-sites-user-list-in-the-apps)] | Every member \[[ASK-130](https://github.com/snapfix/docs/blob/main/ASK.md#ask-130-should-members-who-are-not-admins-see-the-sites-user-list-in-the-apps)] |
| Search                              | On the server                                   | On the device                                                                                                                                             | On the device                                                                                                                                             |
| Site admin box and site permissions | Yes                                             | No                                                                                                                                                        | No                                                                                                                                                        |
| Remove a user                       | Yes                                             | No (hidden)                                                                                                                                               | No (hidden)                                                                                                                                               |
| Groups and roles                    | Groups card                                     | Sheet                                                                                                                                                     | Sheet                                                                                                                                                     |
| Devices                             | "Devices" tab                                   | From the user sheet                                                                                                                                       | From the user sheet                                                                                                                                       |
| Add users                           | Form of up to 10, or a spreadsheet; contractors | Phone, email or QR code                                                                                                                                   | Phone, email or QR code                                                                                                                                   |
| Badges                              | "ADMIN", "CONTRACTOR", "MULTI-SITE"             | None                                                                                                                                                      | None                                                                                                                                                      |


---

# 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/how-the-apps-work/screens/console/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.
