> 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/product/features/onboarding/setup-form.md).

# Setup form

{% 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/product/features/setup-form.md).
{% endhint %}

New customers get a **setup link** from the Snapfix team. The link opens the **setup form** on the web (`setup.snapfix.com/<id>`), where they check their **account** details and logo, add up to 10 **administrators** and up to 100 users by hand or from a spreadsheet, and list up to 1,000 **locations**. Creating the account sends the form to the server, which queues the **setup job**. The job fills in the **site** the setup belongs to, links the people to it, creates a starter **group** and sends each new person an invitation. The page needs no sign-in: the link's ID identifies the setup, and progress is kept in the browser until the form is submitted. This is how new customers are onboarded; there is no sign-up.

## Rules

### The link

* Anyone with the setup link can open the form and submit it. There is no sign-in, the page uses the shared guest login built into its code, and the server accepts a submit while the setup is unfinished.
* A bad link shows the not-found page ("The URL appears to be incorrect", with the support address). Any other load failure, including being offline, shows the same page ([Create your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md#states)).
* A setup works once. When its job finishes, the link shows the not-found page. A submit sent before the job finishes queues a second job, which adds a second starter group.
* Staff create the setup record from the admin app's sales page (`POST /v1/admin/sales/onboarding`); staff work on setups in [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md) and [Billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md).

### The steps

* The form has four steps (account, administrators, users, locations) and a thank-you page, with a progress bar ([Create your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md#layout)).
* **Account:** the name is required and up to 60 characters, the address fields are optional, and the country is required. Name and address arrive pre-filled when the setup has them ([Create your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md#inputs)).
* The country list comes from [`GET /v1/guest/countries`](https://docs.snapfix.com/engineering-reference/api/reference.md). The country field stays disabled until the list loads, but "NEXT" does not wait for it, and a disabled country is left out of the submit (web\_onboarding\_form @ 099b91d4e3, `src/app/components/account/account.component.ts:81-102`).
* The logo is optional and up to 2 MB. The form accepts any image, but the server accepts only jpg, jpeg, png or gif, so another image type is refused on submit (`account-logo-dialog.component.html:4-7`; api\_php\_live\_v2 @ ef3c4319f6, `CreateOnboardDataRequest.php:21-25`).
* **Administrators:** at least one is required, and up to 10 are allowed. Each needs a first name, a last name, an email address and a mobile number. The first is the **Main Admin**, who becomes the owner of the site. The server refuses the owner's mobile number when an active user already has it, unless an active user already has the owner's email ([Create your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md#inputs)).
* **Users:** up to 100, each with a name and an email address or a mobile number. The form catches duplicate emails and phone numbers, also against the administrators ([Create your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md#inputs)).
* **Locations:** up to 1,000 names, no duplicates. The page sends them, but the setup job never saves them (`app/Jobs/Onboarding.php:235-242`, commented out).
* Users and locations can come from an Excel file with the columns the form names ("First Name", "Last Name", "Email", "Country Code", "Cell Phone (Mobile)"; "Location"). A file over the row limit, or one without those columns, clears the list before it is refused (`src/app/components/users/users.component.ts:105-112`).
* The form enforces its limits in the browser only. The server caps the uploaded data at 2 MB and sets no count for administrators, users or locations, and the job sends a message to each new person.

### Creating the account

* "CREATE ACCOUNT" sends everything, and the thank-you page appears when the job is queued, not when the site is ready \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. A refused submit shows the server's message in a toast and keeps every entry ([Create your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md#actions)).
* The setup job makes the owner the site's admin, saves the account details and logo on the site, and invites each new person by email, and by text for people with a mobile number ([`POST /v1/guest/onboarding/{uuid}`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-v1guestonboardinguuid)).
* A person who already has an account is linked to the new site, not created again, and sees the "added to a new site" prompt once instead of a new-user message ([`GET ?action=new_site_status`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-actionnew_site_status)).
* The job creates one group named "Maintenance" (or the next free "Maintenance" name), because the form never sends groups (`Onboarding.php:384-437`) \[[ASK-40](https://github.com/snapfix/docs/blob/main/ASK.md#ask-40-should-the-setup-form-offer-group-templates)].
* The server skips a user whose email it rejects, and one whose email and phone belong to two different existing people, without saying so; the submit still reports success.
* The uploaded data file, with the contact details of everyone listed, is kept in file storage with no end date and never read back.

### Saved progress

* Progress is saved in the browser under the link's ID, so another browser starts empty. Each step is saved when its "NEXT" is pressed, and the locations at the submit. The saved data stays until the submit succeeds, so a reload brings the form back and the person can submit again. Typed rows that "NEXT" did not save are lost on reload.

## Flow

```mermaid
flowchart TD
  link["Staff send the setup link"] --> open["The page loads the setup"]
  open -->|"unknown, finished or offline"| notfound["Not-found page"]
  open --> s1["1. Account details and logo"]
  s1 --> s2["2. Administrators, at least one"]
  s2 --> s3["3. Users, optional"]
  s3 --> s4["4. Locations, optional"]
  s4 --> submit["CREATE ACCOUNT"]
  submit -->|"refused"| toast["Toast with the message, entries kept"]
  toast --> s4
  submit -->|"accepted"| thanks["Thank-you page"]
  submit -.->|"job runs later"| job["Setup job: owner, people, Maintenance group"]
  job -.-> invites["Email or text to each new person"]
```

## Platforms

| Capability                                   | Web                            | iOS            | Android        |
| -------------------------------------------- | ------------------------------ | -------------- | -------------- |
| Set up a site from a link                    | yes                            | no             | no             |
| Account, administrators, users and locations | yes, up to 10, 100 and 1,000   | no             | no             |
| Spreadsheet upload of users and locations    | yes                            | no             | no             |
| Sign-in needed                               | no, the link is the only check | not applicable | not applicable |

The apps have their own setup for people who have no site, with different steps and different endpoints: [Site setup in the app](https://docs.snapfix.com/product/features/onboarding/site-setup.md).

## Screens

* [Create your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md): the four steps, the thank-you page and the not-found page.

## API and data

* [Onboarding API](https://docs.snapfix.com/engineering-reference/api/onboarding.md): [`GET /v1/guest/onboarding/{uuid}`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-v1guestonboardinguuid) loads the setup, and [`POST /v1/guest/onboarding/{uuid}`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-v1guestonboardinguuid) submits it and queues the setup job.
* [API reference](https://docs.snapfix.com/engineering-reference/api/reference.md): `GET /v1/guest/countries`, the country list.
* Tables: [`tPri_Org_OnboardingLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_onboardinglog.md) (the setup, and whether it has finished), [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) (the site), [`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md) and [`tPri_ParentAddress`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentaddress.md) (its address), [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md), [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) and [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) (the people), [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) (the starter group), and [`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md), [`dynamiclink_invitation`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_invitation.md) and [`dynamiclink_user`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_user.md) (the invitations).

## Depends on

* [Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md): the invitations the setup creates, and how the invited people accept them.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the administrators and users the setup adds, and their roles.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md): the "Maintenance" group the setup creates.
* [Site details](https://docs.snapfix.com/product/features/console/site-details.md): the name, address and logo the setup sets.
* [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md): where the form's locations would go. The setup does not save them today.
* [Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md): the links in the invitation emails and texts.
* [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md) and [Billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md): where staff work on setups.

## Edge cases

* **Offline:** the page shows the not-found page on load. A failed submit shows the server's message in a toast and keeps every entry.
* **Reload:** the saved browser data is kept until the submit succeeds.
* **Finished or unknown link:** the not-found page. A second submit before the job finishes is accepted and adds another group.
* **Country list fails:** the country stays disabled, "NEXT" still works, and the submit goes without a country.
* **Limits reached:** the form stops at 10 administrators, 100 users and 1,000 locations. The server does not.
* **Missing permission:** None. The link is the only check.
* **Several sites:** each setup fills one site. The form cannot add people to another site.
* **Time zones:** None. The form has no time zone field.


---

# 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/product/features/onboarding/setup-form.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.
