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

# Site setup in the app

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

Someone with no site of their own can set one up in the mobile app. They name the company or team, and for a company they also pick its **industry** and their role. They then pick the kinds of work they will use Snapfix for, which become **starter groups**, or describe their challenges if they are not sure. Last, they choose a **grid or list** view, and the app asks the server to create the site. The same steps serve people who **join** a company rather than start one, but the join option does not add them to a site ([Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md)). The steps are not reached on iOS today, and on Android only for accounts the server flags for setup. This is a different flow from the web [Setup form](https://docs.snapfix.com/product/features/onboarding/setup-form.md), with different steps and endpoints. An older iOS create-account path still exists, but its last step can't create an account.

## Rules

### Who sees the setup

* The setup opens only for an account that the server flags for setup. The server sets the flag when the account has no group in any site other than its own placeholder site, the one marked `self` (authpy @ 5d5758661c, `model/feature_user_auth.py:710-729`). The old self sign-up actions create that site (php-apis `registerNewUserV9`, `registerNewUserV10` and the single sign-on sign-up).
* On Android the setup opens after a Google, Apple or Microsoft sign-in or a QR sign-up when the flag is set. It also opens at app launch or after the walkthrough while the flag is still set (`SplashActivity.java:516-517`, `WalkthroughActivity.kt:206-207`).
* On Android a password sign-in stores 0 for the flag, so the setup does not open after it (`LoginActivity.kt:570`) \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].
* On iOS nothing stores 1 for the flag. Every sign-in and sign-up path writes 0 and ignores the server's value (ios @ aa31967ac8, `SmsEmailLoginVC.swift:512-513`, `RegisterHelper.swift:23-24`). So the iOS steps are not reached in the current code \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].
* The pre-registration survey opens on Android only, at sign-in, when the server has an active survey for the caller's country and device. The iOS code asks for it only from a sign-in screen that nothing opens ([Pre-registration survey](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/pre-registration-survey.md)).

### The steps

* **Start or join:** two choices, "Start a New Company or Team in Snapfix" and "Join a Company or Team" ([Start or join](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/start-or-join.md)).
* **Company and role:** the company or team name is required, and "Next" checks it with the server (`validate_parent_name`); a taken name shows the server's message ([Company and role](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/company-and-role.md#actions)). The industry is required when starting. It is not asked when joining, and joining uses the industry named "Other"; when that industry is missing, iOS shows an empty role list and Android takes the roles of another industry ([Company and role](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/company-and-role.md#inputs)). The role is required, and its choices depend on the industry.
* **Work types:** at least one is required, unless the person picks "I don’t know yet" ([Work types](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/work-types.md#inputs)). Each work type picked becomes a group in the new site, copied from its template group ([`POST ?action=create_parent_with_templates`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actioncreate_parent_with_templates)).
* **Let us help you** (only after "I don’t know yet"): the challenges text is required. iOS trims spaces and line breaks from it, and Android does not. The "Snapfix can reach out" opt-in is sent as `notify_snapfix_team`, 1 when ticked and 0 when not ([Let us help you](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/let-us-help.md#inputs)).
* **Grid or list:** required, and sent as `reg_task_view_preference` ([Grid or list](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/grid-or-list.md)). Android also saves it on the phone for the task lists.

### Creating the site

* The create call is `create_parent_with_templates` when work types were picked. Otherwise it is `create_parent_without_templates`, which covers "I don’t know yet" and the join path. The join path sends the note "joining a company" and an opt-in of 0 ([Configuring Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/configuring.md#actions)).
* The create call without templates emails `register@snapfix.com` with the person's details and answers every time, even when the opt-in is not ticked \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] ([`POST ?action=create_parent_without_templates`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actioncreate_parent_without_templates)).
* The create call names the user from the app, and the server acts on that user, not on the token.
* If the name was taken by the time the site is created, the server keeps the site's placeholder name without saying so, still applies the rest, and records a HubSpot tag "Joined Existing Parent" in live mode (php-apis @ aee9175122, `class.functions.php:27072-27095`).
* Choosing "Join a Company or Team" does not add the person to the company's site. The iOS code has a message that a company admin can add them with their Snapfix login ("Share login with admin"), but it sits on the unreached iOS path; Android never shows it \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].
* After the create call succeeds, Android opens the group list. Its account-ready popup is commented out, so no first-task step follows \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] (android @ 86068bfeea, `BusinessListingActivity.java:794-815`). The iOS code would show an account-ready popup whose "Start a task" opens the camera and then [First task group](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/first-task.md), but that path is not reached. Setup does not create a first task \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)]. Android's own first-task picker is never opened \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].

## Flow

```mermaid
flowchart TD
  entry["Flagged account, Android"] --> choice{"Start or join"}
  choice -- "start" --> start["Company, industry and role"]
  choice -- "join" --> join["Company and role"]
  start --> work{"Work types"}
  work -- "picks some" --> grid["Grid or list"]
  work -- "I don’t know yet" --> help["Let us help you"]
  help --> grid
  join --> grid
  grid --> create{"Work types picked?"}
  create -- "yes" --> tpl["Create the site with a group per work type"]
  create -- "no, or join" --> notpl["Create the site with the note and opt-in"]
  tpl --> done["Group list"]
  notpl --> done
  create -. "error" .-> alert["Alert with the server's message"]
```

## Platforms

| Capability                       | Web                                                                                                        | iOS                                                                                                                       | Android                                                                                                                           |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Start a new site                 | no; new customers use the [Setup form](https://docs.snapfix.com/product/features/onboarding/setup-form.md) | no, not reached today \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] | yes, for flagged accounts                                                                                                         |
| "Join a Company or Team"         | no                                                                                                         | no, not reached today \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] | yes, with no message after it \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] |
| Pre-registration survey          | no                                                                                                         | never opened                                                                                                              | yes, at sign-in                                                                                                                   |
| Work types or "I don’t know yet" | no                                                                                                         | no, not reached today                                                                                                     | yes                                                                                                                               |
| Grid or list                     | no                                                                                                         | no, not reached today                                                                                                     | yes, also saved on the phone                                                                                                      |
| First task after setup           | no                                                                                                         | in code only, not reached                                                                                                 | no \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)]                            |
| After a failed create call       | no                                                                                                         | "OK" sends again; "Cancel" signs out                                                                                      | one "OK"; nothing is sent again                                                                                                   |

## Screens

* [Pre-registration survey](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/pre-registration-survey.md): the survey after sign-in, on Android.
* [Start or join](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/start-or-join.md): the first setup step.
* [Company and role](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/company-and-role.md): the company name, industry and role.
* [Work types](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/work-types.md): the starter groups.
* [Let us help you](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/let-us-help.md): the challenges text, when work types are not picked.
* [Grid or list](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/grid-or-list.md): the view choice.
* [Configuring Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/configuring.md): the create call and its errors.
* [First task group](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/first-task.md): the first-task screen, which setup does not reach \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].
* [Create account (legacy)](https://docs.snapfix.com/how-the-apps-work/screens/account/create-account.md): an older iOS sign-up path that cannot create an account.

## API and data

* [Onboarding API](https://docs.snapfix.com/engineering-reference/api/onboarding.md): [`POST ?action=list_industries_roles_templates`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actionlist_industries_roles_templates) lists industries, roles and work types. [`POST ?action=create_parent_with_templates`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actioncreate_parent_with_templates) and [`POST ?action=create_parent_without_templates`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-actioncreate_parent_without_templates) create the site.
* Name check: `validate_parent_name` in the [Console API](https://docs.snapfix.com/engineering-reference/api/console.md).
* Survey: [`GET /v1/guest/survey/prereg`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-v1guestsurveyprereg) and [`POST /v1/guest/survey/prereg`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-v1guestsurveyprereg), with the shared guest login.
* Tables: [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) (the site, with its notes and view), [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) (the starter groups), [`reg_industry`](https://docs.snapfix.com/engineering-reference/db/tables/reg_industry.md), [`reg_industry_roles`](https://docs.snapfix.com/engineering-reference/db/tables/reg_industry_roles.md) and [`reg_industry_business_templates`](https://docs.snapfix.com/engineering-reference/db/tables/reg_industry_business_templates.md) (industries, roles and work types), and [`tPri_Log_PreRegSurvey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_preregsurvey.md) (survey answers and views).

## Depends on

* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md) and [App launch](https://docs.snapfix.com/product/features/account/app-launch.md): decide whether the setup opens.
* [Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md): the invitations and QR sign-up, which are the other ways onto a site.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md): the starter groups copied from the work types.
* [Site details](https://docs.snapfix.com/product/features/console/site-details.md): the site's name and the notes the setup saves.
* [Task lists](https://docs.snapfix.com/product/features/tasks/task-lists.md): the grid or list view.
* [Survey setup](https://docs.snapfix.com/product/features/staff/survey-setup.md): staff create the surveys.
* [Setup form](https://docs.snapfix.com/product/features/onboarding/setup-form.md): the web setup that the Snapfix team runs for new customers.

## Edge cases

* **Offline:** on Android nothing is sent at the create step, and nothing is shown (`ConfigureSnapfixViewModel.kt:120-122`). iOS shows the same alert as any other error. The industry, role and work-type lists need a connection to load ([Company and role](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/company-and-role.md#states)).
* **Create call fails:** on iOS, "OK" sends the call again, and "Cancel" clears the local data and signs out. On Android the alert only shows the server's message, which can be internal.
* **Session expiry:** Android refreshes the session and sends the call again (`ConfigureSnapfixActivity.kt:106-119`).
* **Name taken at create time:** the site keeps its placeholder name.
* **Missing permission:** None. A signed-in account is all the setup needs.
* **Limits reached:** None in the app. An industry with no work types leaves "I don’t know yet" as the only way on ([Work types](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/work-types.md#states)).
* **Several sites:** the setup creates one site. An account that already has a site of its own is not flagged, so it never sees the setup.
* **Legacy iOS create account:** cannot finish, because its last step calls a switched-off endpoint.
* **Time zones:** None. The setup has no time zone field.
* **Integrations:** HubSpot, for the "Joined Existing Parent" tag in live mode. On the no-templates path the server also emails the Snapfix team.


---

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