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

# Create a new group

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

Name a new group in the selected site and, if wanted, start it from a template. When it is saved, the app opens or lists the new group.

![Create a new group](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-29d75e8e5bea3b3476930cf0704f8f4c9e389461%2Fcreate-group.png?alt=media)

* **Where:** web: "+" on the Fix "GROUPS" tab, or the plus icon in its empty state (dialog "Create a new Group"); iOS: "Create a new group" in the top bar "+" menu, or the add-group button in the groups header (screen "Create a new Group"); Android: "Create a new group" in the "+" menus of the Groups tab and the Fix tab (screen "Create a New Group")
* **Who:** the users each platform shows the button to ([Groups](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-list.md#platform-differences)). The web's create call needs the site's "Create New Group" right and answers "Access denied" without it. The apps save through the sync, which checks no right.
* **Feature:** [Groups](https://docs.snapfix.com/product/features/groups/groups.md)

The group is always created in the selected site; no screen offers another site.

## Getting here

* **Web:** the dialog closes after a successful create and the new group's task list opens (`/group/:id/tasks`).
* **iOS:** after "Start" the app returns to the Fix tab. A banner "New group created : {name}" shows for three seconds, with a button that opens the new group's Users tab ([Find user to add](https://docs.snapfix.com/how-the-apps-work/screens/groups/find-user.md)).
* **Android:** after the group is saved, the screen closes and the Groups tab shows the new group.
* **Back:** cancel or back closes the screen. Nothing is saved.

## Layout

### Web

A dialog, 400 px wide, titled "Create a new Group":

1. "Give your group a name that best describes the tasks you will create together."
2. "Group name" with "\*", and the field "ex. Maintenance, Electrical or Fire safety".
3. "OR", "Need some inspiration?" and "Pick from one of these templates instead.", then the templates, each with its image and name and a radio button, sorted by their order. None is picked at first.
4. "Cancel" and "Start Group".

### iOS

The screen "Create a new Group" has the name field, the list of templates with check marks, and the start button. The site field is hidden.

### Android

The screen "Create a New Group" has the name field, the list of templates and the start button. The first-group flow of the setup screens ("Create your first group", then "Share group : {name}" with add-user steps) is part of the retired setup flow \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] and is not reached from the Groups tab.

## Inputs

| Field      | Type            | Required | Default                   | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Group name | Text            | Yes      | Empty                     | Web: up to 100 characters; typing stops there, so "Your input exceeds the maximum allowed length of 100 characters" shows only for a value set by a script. An empty field shows "Please enter a group name" once it has been left. A name of spaces keeps "Start Group" disabled with no message. Markup in the name is accepted. iOS: the start button is enabled while the field has text. Android: up to 100 characters; the start button is enabled while the name isn't blank. |
| Template   | One of the list | No       | None (the blank template) | Picking one puts the template's name into the name field, which can be changed. Web templates come from [`GET /webcust-list-templates`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-webcust-list-templates); the apps load theirs from [`?action=webcust_list_templates_jwt`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actionwebcust_list_templates_jwt).                                                                      |

## Actions

| Action                                    | Who                       | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                            | API                                                                                                                                                                                                                                                                                 |
| ----------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Start Group" (web)                       | Users with the site right | First compares the name, ignoring case and outer spaces, with the groups loaded in the list. A match shows "Group name already exists" and sends nothing. Otherwise creates the group, shows a success state for 1.5 seconds, closes and opens the group. Any other taken name (an archived group, one on a later page, one the user isn't in) is refused by the server, and its text "The name has already been taken." shows in an alert while the dialog stays open. | [`POST /v1/app/businesses`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-v1appbusinesses) with `parent_uuid`, `name` and, with a template, `template_uuid`                                                                                                     |
| "Start" with a template (iOS, Android)    | Users the platform allows | Needs a connection. Checks the name against the device's groups, then on the server. A taken name shows "A group with this name already exists. Choose another one." under the field. Otherwise the server copies the template into the site, and the app reloads its groups.                                                                                                                                                                                           | [`?action=check_duplicate_business`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-actioncheck_duplicate_business), then [`?action=webcust_clone_template`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actionwebcust_clone_template) |
| "Start" without a template (iOS, Android) | Users the platform allows | Checks the name the same way. Then saves the group on the device, with its address set to its name, the default statuses and the user as admin, and the sync sends it later. Without a connection (Android) or when the server check fails (iOS), only the device check runs. Group saves through the sync don't stop a duplicate name.                                                                                                                                 | [`?action=check_duplicate_business`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-actioncheck_duplicate_business), then [`?action=save_pri_business`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-actionsave_pri_business)               |
| Pick a template                           | Anyone on the screen      | Web: picks it and fills the name. iOS and Android: tick the row, which fills the name; tapping it again clears the pick.                                                                                                                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                                                                                   |
| Cancel                                    | Anyone                    | Closes without saving. On the web, not while the group is being created.                                                                                                                                                                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                                                                                   |

A new web group without a template gets the address "New group" and the statuses "New tasks", "Tasks in progress" and "Completed tasks", from the blank template ([`POST /v1/app/businesses`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-v1appbusinesses)).

## States

* **Loading:** web shows a spinner in the template area until the list loads, and a loading state on "Start Group"; the dialog can't be closed meanwhile. The apps show "Creating group..." while they check and create.
* **Empty:** with no templates, the template area is empty and only the name is used.
* **Error:** web: a refused create shows the server's message in an alert and keeps the dialog open. iOS and Android: a failed template copy shows "Something went wrong"; on Android a failed name check does too.
* **No permission:** see **Who**.
* **Offline (mobile):** a template needs a connection on both apps. Without a template, both apps check only the device's groups and save the group for a later sync: Android when it has no connection, iOS whenever the server check fails.

## Dialogs and sheets

* **Group name already exists** (web alert): "A group with this name already exists for the site "{site}". You cannot create a second group with the same name.", with "OK".
* **New group created** (iOS banner).

## Platform differences

* **Who can create:** see [Groups](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-list.md#platform-differences).
* **Name check:** web checks the loaded list and the server refuses any other taken name; the apps check their device copy, then the server, before they create.
* **Save:** web creates the group on the server at once; the apps copy a template on the server, or save a blank group on the device and sync it.
* **Address of a blank group:** web "New group"; the apps the group's name.
* **After creating:** web opens the new group; iOS shows a banner on the Fix tab; Android goes back to the Groups tab.
* **Title:** "Create a new Group" on web and iOS, "Create a New Group" on Android.


---

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