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

# Create your Snapfix 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/onboarding/setup-form.md).
{% endhint %}

A new customer checks and completes the account details, administrators, users and locations that the Snapfix team prepared, then creates the account in one submit.

* **Where:** web (the `web_onboarding_form` app): setup.snapfix.com `/:id`, where `:id` is the setup record's ID. Staff copy the link from the "Hubspot Deals" page of the admin app (webadmin\_angular); its test host is setuptest.snapfix.com. `/` and every other path show the [not-found page](#not-found-page). The browser tab is titled "Snapfix Web".
* **Who:** anyone with the link. There is no sign-in. Every call sends the guest login built into the page. The record ID is the only check on the setup itself, so whoever holds the link can read the record and submit it, naming any administrator.
* **Feature:** [Setup form](https://docs.snapfix.com/product/features/onboarding/setup-form.md)

![Create your Snapfix account](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-136e21589fc45b55d655f2bcc53f5bc5633bdd8f%2Fsetup-form.png?alt=media)

The screenshot shows the not-found page, the only state the live pass could reach without a valid setup link \[[ASK-41](https://github.com/snapfix/docs/blob/main/ASK.md#ask-41-which-setup-link-can-the-live-pass-open)]: the Snapfix logo, "THE URL APPEARS TO BE INCORRECT", the support address and "404". The steps below are described from code.

The production build calls the guest API at `https://z4.snapfix.com`. The `staging-live` build calls `https://y4.s6eur.com`, and the `staging` and `development` builds call `https://b4.s6eur.com` \[[ASK-8](https://github.com/snapfix/docs/blob/main/ASK.md#ask-8-confirm-the-environments)].

The form creates the site with one api\_php\_live\_v2 request that queues the `Onboarding` job. The mobile apps create a site a different way ([Configuring Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/configuring.md)) \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].

## Layout

The page is one centred card. A progress bar sits at the top with no step names: 0 on step 1, then 25, 50, 75 and 100. A back arrow (alt text "Arrow Left") sits at the bottom left on steps 2 to 4. The Snapfix logo sits at the bottom of the card. A version label sits at the bottom right of the window: the code at the pinned commit sets "v1.0.0", and the live page shows "v1.0.2". Toasts last five seconds, at most three at once, newest on top.

While the record loads, the card shows a spinner. After it loads, one step shows; the other step components stay on the page, hidden.

1. **Account** (0): "Create your Snapfix Account". The logo, the account form, then "NEXT".
2. **Administrators** (25): "Add Administrators" and "Add up to 10 administrators.". The form ("Account Administrator Details") on the left, the people already added on the right. Under them: "Account administration, new users and other settings can be managed in ‘Manage Snapfix Account’ on Snapfix web." Then "NEXT".
3. **Users** (50): "Upload Users", or "Review User Details" while an uploaded list is on screen. See [Users](#users).
4. **Locations** (75): "Upload Locations". See [Locations](#locations).
5. **Thank you** (100), after a successful submit, with no back arrow: "Thank you for joining Snapfix!", "An invite will be sent by SMS or email to the users you just added.", "Don’t forget to remind them to check their spam folder.", "Please go to your email to verify your account.", "We can’t wait to see you all there!" and "Happy Snapfixing!". The submit returns before the job has run.

Field error texts show only while that field has focus, so leaving a bad field hides its message and only the red outline stays. The users and locations lists add "The fields outlined in red contain an error, click in the field to see error type." while a row is invalid. Phone errors on a listed user row are hidden on blur, except "Duplicate phone number", which stays.

## Inputs

### Account

| Field               | Type       | Required | Default                                          | Rules and messages                                                                                                                                                                                                                                                                                                                                                                |
| ------------------- | ---------- | -------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Logo                | Image file | No       | The record's logo, if it has one                 | "Upload Account Logo" opens [Upload Account Logo](#upload-account-logo). The dialog takes any image type up to 2 MB. The API takes only jpg, jpeg, png or gif up to 2048 KB, so another image type fails only at "CREATE ACCOUNT".                                                                                                                                                |
| "Account Name \*"   | Text       | Yes      | The record's name, unless this browser saved one | Placeholder "Enter your company name". Up to 60 characters. "Please enter an account name" shows while the field has focus, for any error on it.                                                                                                                                                                                                                                  |
| "Account Address"   | Text       | No       | The record's address                             | Placeholder "Enter your company address". Up to 100 characters.                                                                                                                                                                                                                                                                                                                   |
| Second address line | Text       | No       | Empty                                            | No label or placeholder. Up to 100 characters. The record has no second line, so a reload before "NEXT" clears it.                                                                                                                                                                                                                                                                |
| "County/State"      | Text       | No       | The record's state                               | Placeholder only. Up to 60 characters.                                                                                                                                                                                                                                                                                                                                            |
| "Postcode"          | Text       | No       | The record's postal code                         | Placeholder only. Up to 10 characters.                                                                                                                                                                                                                                                                                                                                            |
| "City"              | Text       | No       | The record's city                                | Placeholder only. Up to 60 characters.                                                                                                                                                                                                                                                                                                                                            |
| "Country"           | Drop-down  | Yes      | The record's country code                        | Options are the country names from `GET /v1/guest/countries`; the value is the country code. The field is disabled, with a spinner, until the list arrives, and stays disabled when the call fails. A disabled field does not count in the form check, so "NEXT" works with no country and the saved account has no `country`. Once enabled and empty: "Please choose a country". |

The record's name, address and logo are filled in about half a second after the record arrives, for each field this browser has no saved value for. The step is usable before that, so a value typed into an empty field in that half-second is replaced.

"NEXT" is disabled while the form is invalid; its tooltip reads "Please fill in all required fields".

### Administrators

At least one, at most 10. The first row is headed "Main Admin" and becomes the site's owner; every later row is headed "Admin". Each row shows the name, email and phone, and a minus button removes it. Administrators after the first are saved on the site as users, though their group role is admin.

| Field          | Type                        | Required        | Default                      | Rules and messages                                                                                                                                                                                                                                              |
| -------------- | --------------------------- | --------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "First Name"   | Text                        | Yes             | Empty                        | Up to 30 characters. "Please enter a first name" while focused.                                                                                                                                                                                                 |
| "Last Name"    | Text                        | Yes             | Empty                        | Up to 30 characters. "Please enter a last name" while focused.                                                                                                                                                                                                  |
| "Email"        | Text                        | Yes             | Empty                        | Up to 70 characters. The browser's email check plus the [email pattern](#email-pattern). "Please enter an email address" when empty, "Please enter a valid email address" when a check fails.                                                                   |
| "Phone number" | Phone with a country picker | Marked required | Ireland (`ie`), no IP lookup | Labels "Code", "Search", "No countries found", "Mobile" and the hint "Select country and type your phone number". Messages "Mobile is required" and "Mobile is not valid". The form control itself has no validators; the phone component is passed `required`. |

The plus button is disabled until the form is valid and fewer than 10 people are listed. Its tooltip reads "Please fill in all required fields", "Please enter a valid email address", or "The maximum allowed administrator count is 10". A new row whose email (ignoring case and surrounding spaces) or phone (exact text) matches a listed person is refused with [Administrator already listed](#administrator-already-listed). On a return visit the saved rows load again; a saved row that matches an earlier one is skipped with no dialog, and every saved row after it is left out.

"NEXT" is disabled while the list is empty; its tooltip reads "Please complete the ‘Account Administrator Details’ form and click the plus (+) button".

### Users

Optional, up to 100. A spreadsheet, or one person at a time. The intro, while no uploaded list is on screen:

* "All users added now will have a user profile created and will be sent an email / SMS to verify their profile."
* "Upload Users", "Simply download the template, and enter your users in the order indicated. Save it as a .XLS / .XLSX file, and upload it. Maximum of 100 users per upload."
* "Download Template" (the file `User Upload Template.xlsx`) and "Upload Users", or "Review Uploaded Users" once a file has been read.
* "OR", "Enter User Details", "You can enter your team details in the form below:", "A user can have an email or phone, or both." and "Phone numbers must include the country code e.g. +1 212 123 4567".

The add row:

| Field      | Type                        | Required       | Default        | Rules and messages                                                                                                                                                                                                                    |
| ---------- | --------------------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| First name | Text                        | Yes            | Empty          | Placeholder "e.g. John". Up to 30 characters. "Please enter a first name" while focused, for any error on the field.                                                                                                                  |
| Last name  | Text                        | Yes            | Empty          | Placeholder "e.g. Greene". Up to 30 characters. "Please enter a last name" while focused, for any error on the field.                                                                                                                 |
| Email      | Text                        | Email or phone | Empty          | Placeholder "<name@domain.com>". Up to 70 characters. The [email pattern](#email-pattern) when filled: "Please enter a valid email address". "Duplicate email address" when another row has it, ignoring case and surrounding spaces. |
| Phone      | Phone with a country picker | Email or phone | Ireland (`ie`) | "Number is not valid". "Duplicate phone number" when another row's phone matches with spaces removed.                                                                                                                                 |

A listed row with neither email nor phone shows "Please enter an email address or phone number". The plus button is disabled while the row is incomplete or 100 people are listed; its tooltip reads "Please provide user details", "Duplicate email address", "Duplicate phone number", "Please enter a valid email address", "An email address or phone number is required", or "The maximum allowed user count is 100".

On the review of the list: minus removes a row (red while the row is invalid), "CLEAR ALL" opens [Remove Users](#remove-users), and "Click the minus to remove the entire row, and “clear all” to start over." "NEXT" is disabled while any listed row is invalid; its tooltip reads "Some of the user forms contain an error". With no rows, "NEXT" is enabled.

A spreadsheet is read from its first sheet; empty cells come through empty. The first row must have the columns "First Name", "Last Name", "Email", "Country Code" and "Cell Phone (Mobile)". When a row has both a country code and a phone, the phone becomes "+ `". Choosing a file clears the current list first, and only then checks it: more than 100 rows toasts "The file contains more than 100 users. Please review the file and upload it again.", and missing columns toast "The uploaded file does not contain the required fields for the upload process. Please provide a file based on the simple template." Either way the earlier rows are gone. A value from a file that is longer than the field allows marks the field invalid; a long first name shows "Please enter a first name".`

`"NEXT" refuses a user whose email or phone equals a saved administrator's, with` [`Same person as an administrator`](#same-person-as-an-administrator)`. The phone is compared as exact text here.LocationsOptional, up to 1,000. There is no control to type the first location: the empty step offers only the spreadsheet."Upload Locations", "Simply download the template, and enter your locations" (no full stop), "Save it as a .XLS / .XLSX file, and upload it." and "Maximum of 1000 locations per upload.""Download Template" (Location Upload Template.xlsx) and "Upload Locations".The same "‘Manage Snapfix Account’" sentence as the administrators step.After a file is read, each row is a text field:The file's first row must have a "Location" column. More than 1,000 rows toasts "The file contains more than 1000 tags. Please review the file and upload it again."; a missing column toasts the same missing-fields message as for users. "CREATE ACCOUNT" is disabled while any row is invalid; its tooltip reads "Please review and correct the highlighted errors before submitting." The names are sent as tags, and the server drops them.Email patternAdministrators and users get a second check after the browser's own: lower-case letters, digits and ._%+-, then @, a lower-case host, a dot and a two- to four-letter ending, anchored only at the end. "Jane@Example.com", "JANE@example.com" and "jane@example.online" fail with "Please enter a valid email address", which the server would accept. The check also refuses an address whose last two dot-separated parts are equal (jane@example.com.com) and an address with more than one +.ActionsThe submit is a multipart request:data: a JSON file named onboard.json with account (name, address1, address2, state, postalCode, city, country), admins and users (each firstname, lastname, email, countryCode, mobile) and tags (the location names). The phone is split after a leading "+" is removed: the part before the first space is the country code, and the rest, with dashes removed, is the number. It never sends groups, so the job gives the site one group named "Maintenance".logo: sent when a logo was chosen in this browser. A logo that came only from the record is shown but not sent.The server answers once the job is queued, not when the account exists [`[`ASK-13`](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)`]. In short, the job (`[`onboarding API`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-v1guestonboardinguuid)`) updates the site with the account details, makes the first administrator its admin (reusing an existing account with that email), adds the other people, creates the "Maintenance" group and invites each new person. It silently skips a user whose email PHP rejects, or whose email and phone belong to two different existing people, and the thank-you page still promises an invite. For an owner email that is new, the server refuses a mobile number that another user has: "It appears this mobile number is already in use by another user. Please contact Snapfix (support@snapfix.com) if this is your number." The data file is also stored in the file store and never deleted.Saved progressEverything is kept in the browser's local storage under keys that end with the record ID: the step, the account, the logo, the administrators, the users (with whether they came from a file) and the locations. Each step is saved when its "NEXT" is pressed, and the locations when "CREATE ACCOUNT" is pressed. Rows not yet added with the plus button are lost on a reload. A successful submit deletes every key, and the thank-you step itself is not stored, so a reload of a finished link shows the not-found page.Submitting twiceThe record stays open until the job sets its completion time at the end. A reload during the spinner brings the saved form back, and a second "CREATE ACCOUNT" is accepted and runs the job again, adding a second set of groups and invites. The page itself only blocks a second click while the answer is in flight.States`**`Loading:`**` ``a spinner in the card until the record arrives; a spinner in the country field until the countries arrive; a spinner over the card while "CREATE ACCOUNT" runs. Restoring more than 50 saved users or more than 100 saved locations opens` [`Upload progress`](#upload-progress)`.`**`Empty:`**` ``administrators need at least one row. Users and locations can be submitted empty.`**`Error:`**` ``a failed record load shows the not-found page. A failed submit toasts the server's message, such as "Admin email address is not valid", and stays on locations. A data file that is not JSON fails inside validation instead of with a validation message.`**`No permission:`**` ``none. The link is the only key.`**`Offline (mobile):`**` ``web only. Offline, the link shows the not-found page.Dialogs and sheetsNot-found pageThe Snapfix logo, "The URL appears to be incorrect" (shown in capitals), "Please contact your administrator or email us at support@snapfix.com" (the address is a mail link) and "404".Upload Account Logo"Upload Account Logo", a drop area with "Drag and drop an image here", "OR" and "Choose an image", then "Cancel" and "Save". "Save" is disabled until a file is accepted, with the tooltip "Please choose an image". The drop area's own error (wrong type, over 2 MB) is toasted. "Save" shows the image on step 1 and keeps it in the browser.Administrator already listed"The email and mobile number are already in use", "The mobile number is already in use" or "The email is already in use". Then "First Name:", "Last Name:", "Email:" and "Mobile:" for the person already listed, with the matching value in red. "Close". The new row is not added.Same person as an administratorOpened by "NEXT" on users. The same three titles followed by "for the Admin" (for example "The email is already in use for the Admin"), and the administrator's four lines. "Close". The step does not change.WarningTitled "Warning", in three versions:An unsaved add row on "NEXT" or the back arrow: "It seems you’ve entered data but haven’t saved it using the plus (+) button.", "Are you sure you want to continue without saving?" and "To save your data, click the plus (+) button before proceeding to the Next or Previous step." Buttons "Stay and Save the Data" and "Proceed Without Saving".Typed users when a file is opened: "You have entered data manually but now want to upload users from a file." (or "… review uploaded users." when a file is loaded), "Please note that any manually entered data will be overwritten and replaced with the data from the uploaded file." (or "… uploaded users."), and "Are you sure you want to proceed?". Buttons "Cancel and Keep Manual Data" and "Proceed and Upload File" (or "Review Uploaded Users").Typing into the add row while an uploaded list exists and the intro shows: "You have uploaded user data but now want to add data manually.", "Please note that all uploaded user data will be overwritten and replaced with the manually entered data." and "Are you sure you want to proceed?". "Cancel and Review Uploaded Users" returns to the review; "Proceed and Remove Uploaded Users" clears the list.Before a file is opened, the check looks at the first listed user row if there is one, otherwise at the add row; later rows are not checked.Upload File"Upload File", a drop area with "Drag and drop a file here", "OR" and "Choose a file", then "Cancel" and "Save". It takes an Excel file (.xlsx or .xls) and has no size limit. "Save" is disabled until the first sheet has at least one row; tooltips "Please choose a file" and "Uploaded file is empty". The drop area's own error is toasted. "Save" fills the list behind` [`Upload progress`](#upload-progress)`.Upload progress"Uploading users..." or "Uploading tags...", a spinner and a percentage that never shows above 100. It cannot be closed, and closes itself two seconds after the percentage reaches 100. Locations count each row as it is added. Users count a row only at its first form status change after the row is created, so the dialog can stay up when rows never change status. Not seen live: it needs a real upload.Remove Users"Remove Users", "Are you sure you want to remove all uploaded users?", "Cancel" and "Remove". The text says "uploaded" also when the rows were typed.Platform differencesWeb only. The mobile apps set up a site on the other screens of this area.`


---

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