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

# Onboard account

{% 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. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/staff/onboard.md).
{% endhint %}

Staff create a new site with its account admin, its other users and its groups in a three-step form, sent in one request.

* **Where:** admin app `/onboard`; menu "Onboard"
* **Who:** anyone signed in to the admin app ([Access](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#access)). The creating call needs only a signed-in user, so anyone signed in can create sites and accounts for any email address or phone number ([`admin_onboard_parent`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_onboard_parent)).
* **Feature:** [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md)

## Layout

1. **Title.** "Onboard Account".
2. **Steps.** "Account Details", "Users Details" and "Group Details", stacked vertically when the window is 800 px wide or less. One step shows at a time, with its buttons under the form. Clicking a step header opens that step: "Users Details" once the account details are valid, "Group Details" once the users are valid, and none while the request runs. "Group Details" does not check the account details, so staff can make them invalid, open "Group Details" from its header and send them; the server refuses an empty name or address, but takes one shorter than four characters.
3. **Account Details.** "Name", "Address" and "Timezone Name", then "Next".
4. **Users Details.** A divider "Account Admin" with the admin's form, then a divider "Account Users" with one form per added user, each with a remove button. Then "Add User", "Previous" and "Next".
5. **Group Details.** One form per group, each with a remove button. Then "Add Group", "Previous" and "Onboard".

## Inputs

Account Details:

| Field         | Type                                                | Required | Default | Rules and messages                                                                                                                                                              |
| ------------- | --------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name          | Text                                                | Yes      | Empty   | At least 4 characters: "Name is required"; "Name must be at least 4 characters". The server refuses a name a live site already has: "Business already exists with the name ''". |
| Address       | Text                                                | Yes      | Empty   | At least 4 characters: "Address is required"; "Address must be at least 4 characters".                                                                                          |
| Timezone Name | Select with search, placeholder "Select a Timezone" | Yes      | Empty   | The time zone list. "Timezone Name is required". The server ignores the zone, so every site made here starts in Europe/Dublin.                                                  |

Each user, the account admin and every account user:

| Field                                               | Type                      | Required                                                      | Default | Rules and messages                                                                                                                                                                                                                                  |
| --------------------------------------------------- | ------------------------- | ------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| First Name ("\* First Name")                        | Text                      | Yes                                                           | Empty   | "First Name is required"                                                                                                                                                                                                                            |
| Last Name ("\* Last Name")                          | Text                      | Yes                                                           | Empty   | "Last Name is required"                                                                                                                                                                                                                             |
| Password ("\* Password")                            | Text, shown as typed      | Yes                                                           | Empty   | "Password is required". The button beside it, "Generate", fills in a random 10-character password of upper and lower case letters and digits.                                                                                                       |
| Email ("Email")                                     | Text                      | Yes, unless a country code and a mobile number are both given | Empty   | "Email is not valid"; "Email is required" when there is no email and no mobile number; "Duplicate email found". An address with no dot in its domain, such as `jane@example`, passes the form, and the server refuses it with "invalid user email". |
| Country code ("Country code") and Mobile ("Mobile") | Two numbers, side by side | Both, or neither                                              | Empty   | "Mobile is not valid" when only one is given; "Duplicate mobile number found".                                                                                                                                                                      |

The duplicate checks compare each account user with the admin and the users above it, and mark the later row. A form joins the checks only after its first change: while an earlier user form is untouched, or the admin form when a user is filled in first, the checks break, duplicates go unmarked, and "Next" and "Onboard" do nothing, with no message. Emails and numbers that already have an account are refused by the server when "Onboard" is pressed ("'' already exists").

Each group:

| Field                        | Type                        | Required | Default | Rules and messages                                                                                                                                  |
| ---------------------------- | --------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name ("\* Name")             | Text                        | Yes      | Empty   | "Name is required"; "Duplicate name found" when an earlier group has the same name.                                                                 |
| Admin ("\* Select Admin")    | Select                      | Yes      | Empty   | "Admin is required". Lists everyone on the users step, as "First Last - email", or "First Last - country code mobile" for someone without an email. |
| Users ("Select User(s)")     | Multi-select, one tag shown | No       | Empty   | The same people; the group's admin is listed but disabled. Choosing an admin removes that person from Users.                                        |
| Template ("Select Template") | Select                      | No       | Empty   | The group templates, by name.                                                                                                                       |

"Onboard" checks only the group forms, and also goes ahead with no group at all \[[ASK-199](https://github.com/snapfix/docs/blob/main/ASK.md#ask-199-should-onboarding-require-at-least-one-group)].

## Actions

| Action                 | Who              | What happens                                                                                                                                                                                                                                                                                                                                 | API                                                                                                                                                                                                                                                         |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the page          | Anyone signed in | Loads the time zones and the group templates.                                                                                                                                                                                                                                                                                                | [`GET ?action=read_parent_timezones`](https://docs.snapfix.com/engineering-reference/api/reference.md), [`POST ?action=webcust_list_templates_jwt`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actionwebcust_list_templates_jwt) |
| Next (Account Details) | Anyone signed in | Opens Users Details. Disabled until Name, Address and Timezone Name are valid.                                                                                                                                                                                                                                                               | None                                                                                                                                                                                                                                                        |
| Add User               | Anyone signed in | Adds an empty user form.                                                                                                                                                                                                                                                                                                                     | None                                                                                                                                                                                                                                                        |
| Next (Users Details)   | Anyone signed in | Opens Group Details and adds an empty group form, every time, so going back and forward again adds more. Disabled until the admin form and every user form are valid.                                                                                                                                                                        | None                                                                                                                                                                                                                                                        |
| Add Group              | Anyone signed in | Adds an empty group form. Disabled while the request runs.                                                                                                                                                                                                                                                                                   | None                                                                                                                                                                                                                                                        |
| Previous               | Anyone signed in | Goes back one step; the entries stay. On the group step it is disabled while the request runs.                                                                                                                                                                                                                                               | None                                                                                                                                                                                                                                                        |
| Remove                 | Anyone signed in | Deletes that user or group row.                                                                                                                                                                                                                                                                                                              | None                                                                                                                                                                                                                                                        |
| Generate               | Anyone signed in | Fills in that user's password.                                                                                                                                                                                                                                                                                                               | None                                                                                                                                                                                                                                                        |
| Onboard                | Anyone signed in | Sends the site, the users and the groups in one request: the account admin as the site's admin, and each user with the role each group form gives them. Disabled while a group form is invalid. On success "Success" shows, and the form clears and goes back to the first step; on failure the server's message shows and the entries stay. | [`POST ?action=admin_onboard_parent`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_onboard_parent)                                                                                                                          |

The new site gets the customer type `admin_quick_onboard`, which the [Account](https://docs.snapfix.com/how-the-apps-work/screens/staff/accounts.md) page shows as "Admin Quick Onboard" \[[ASK-200](https://github.com/snapfix/docs/blob/main/ASK.md#ask-200-which-customer-type-should-a-site-made-by-onboard-have)]. Only the account admin gets a site membership; the other users get only their group memberships.

## States

* **Loading:** "Timezone Name" shows a loading state until the zones arrive. While the request runs, "Onboard" shows a spinner, and the step headers, "Previous" and "Add Group" are disabled.
* **Empty:** an empty time zone or template list gives no options, with no message.
* **Error:** a failed time zone load shows the server's message; a failed template load shows nothing. A failed "Onboard" shows the server's message and keeps the entries.
* **No permission:** none in the app.


---

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