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

# Joining a site

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

People join a site that already uses Snapfix through an invitation; there is no sign-up. An **invitation link** comes by email or text message, names the site, the groups and the role in each, and lets a new person set a password and start. A **QR invitation** is shown to the person, and gives them a short **sign-up** in the app with their profile, a password and a verification link. A person who is already signed in joins a site by opening a QR invitation: the server adds them at once. Someone who signs in without a site can also pick "Join a Company or Team" in the app's setup; that option does not add them to a site, and it is described in [Site setup in the app](https://docs.snapfix.com/product/features/onboarding/site-setup.md).

## Rules

### Invitation links

* An invitation link works only while its invitation is pending, existing or onboarded; otherwise the server answers "invalid reference". It has no time limit ([Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md#opening-a-link)).
* On a computer the link goes through [Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md). A person with no temporary password is signed in and opens Fix; a new person gets the page to set a password ([Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md#signing-in-from-a-link-web)).
* The web page reads the link and signs in the account that the link names. It does not check that the link belongs to that account.
* The web shares the password page between invitations and resets. For an invitation it greets the person by name and links the terms of service and fair usage policy ([Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md#layout)).
* The password needs at least 8 characters with a number, a lowercase and an uppercase letter, and the confirmation must match ([Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md#inputs)).
* On the web, saving the password signs the person in and opens Fix, or shows "Password reset successful" and opens sign-in when there is no stored session ([Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md#actions)).
* In the apps, the password screen first asks for a six-digit code when the account needs verification, then saves the password and opens the data download ([Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md#actions)).
* A signed-in person who opens an invitation link sees the "added to a new site" prompt. The prompt lists each site once ([`GET ?action=new_site_status`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-actionnew_site_status)). That GET also marks the sites as seen, so it writes data.

### QR invitations

* A QR invitation is the same kind of invitation as a code to scan. Admins make it in the app, and replacing it makes the printed code stop working ([Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md#making-qr-invitation-links)).
* QR sign-up is only in the apps. It asks for a first and last name and an email or phone (Android also takes an optional photo), then a password ([Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md#inputs)).
* An email or phone number that already has an account gets an alert and is sent to log in ([Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md#dialogs-and-sheets)).
* The server sends a **verification link**, not a code, by email or text, and stores the sign-up form. The account is made from the form when the link is opened, and the person is then signed in. The apps show six code boxes, but no code is checked (authpy @ 5d5758661c, `model/feature_user_auth.py`, `_generateVerificationCodeForQROnboarding` and `_temporaryRegisterQRUser`; `model/feature_token_ops.py:3598-3615`).
* The first new account made from a QR invitation uses up the link. After that, the link reports "invitation expired" to everyone, signed in or not (`feature_token_ops.py:3559-3560`, `:3608-3610`).
* A signed-in person who opens a QR invitation is added at once to the site's groups, with the group roles that the link gives, admin included. The server emails or texts them that they were added. This does not use up the link, and QR links have no time limit.
* The server does not check who made a QR invitation or whether the maker may grant its roles.
* On the web, a QR link ends at "Something went wrong" and sign-in.

### After joining

* When a new person accepts an invitation or finishes a QR sign-up, the site admins get an email or text and a push that the person is active (`model/feature_user_auth.py:1290-1350`). See [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md).
* The person then signs in with the groups the invitation gave them, and the site's data downloads as on any sign-in ([App launch](https://docs.snapfix.com/product/features/account/app-launch.md)).

## Flow

```mermaid
flowchart TD
  open["Opens an invitation or QR link"] --> signed{"Signed in?"}
  signed -- "yes, QR link" --> join["Server adds the person to the site and its groups"]
  join --> prompt["Added to a new site prompt"]
  signed -- "yes, invitation" --> prompt
  signed -- "no, invitation" --> pw["Sets a password"]
  pw --> home["Signed in, opens the app"]
  signed -- "no, QR link (apps)" --> profile["Name, and email or phone"]
  profile -- "account already exists" --> exists["Alert: log in instead"]
  profile -- "Next" --> pass["Password"]
  pass --> verify["Verification link by email or text"]
  verify --> made["Account made from the form, signed in"]
  made -.-> notify["Site admins told the person is active"]
```

## Platforms

| Capability                                | Web | iOS                                                                                                                   | Android                                                                                                                                              |
| ----------------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invitation link: set a password and start | yes | yes                                                                                                                   | yes                                                                                                                                                  |
| Code on the invitation password screen    | no  | when the account needs verification                                                                                   | when the account needs verification                                                                                                                  |
| QR invitation: new account                | no  | yes                                                                                                                   | yes, also a photo                                                                                                                                    |
| Signed-in person joins by QR link         | no  | yes                                                                                                                   | yes                                                                                                                                                  |
| "Added to a new site" prompt              | yes | yes                                                                                                                   | yes                                                                                                                                                  |
| "Join a Company or Team" option           | no  | not reached today \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] | after an SSO or QR sign-up that the server flags \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] |

## Screens

* [Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md): the password page for an invitation link, on web, iOS and Android.
* [Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md): the web page that reads a link from an email or text message.
* [Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md): the QR sign-up on iOS and Android.
* [Start or join](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/start-or-join.md): the "Join a Company or Team" option, which is part of [Site setup in the app](https://docs.snapfix.com/product/features/onboarding/site-setup.md).

## API and data

* [Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md): reading a link (`GET /dl-ctx/{dynamicLinkUUID}`), checking the contact (`POST /validate-username-v3`), saving the password (`?action=set_user_password_v9`), and the QR sign-up steps (`POST /generate-verification-f3d8x-v11`, `POST /reg-f3d8x-v11/{dynamiclinkUUID}`).
* [`POST /v1/app/generate-dynamic-link`](https://docs.snapfix.com/engineering-reference/api/account.md#post-v1appgenerate-dynamic-link): makes a QR invitation for groups of one or more sites.
* [`GET ?action=new_site_status`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-actionnew_site_status): lists the sites a person was added to, once.
* Tables: [`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md) (each link, its type and how often it was used), [`dynamiclink_invitation`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_invitation.md) (the site and group roles each link grants), [`dynamiclink_user`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_user.md) (each invited person and their status), [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) (site membership) and [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) (group membership).

## Depends on

* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the invitations that site admins send from the app.
* [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the group roles that an invitation grants.
* [Setup form](https://docs.snapfix.com/product/features/onboarding/setup-form.md) and [Site setup in the app](https://docs.snapfix.com/product/features/onboarding/site-setup.md): the setup that sends invitations, and the "Join a Company or Team" option.
* [Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md): the links in invitation emails and texts, and how the apps open them.
* [Password reset](https://docs.snapfix.com/product/features/account/password-reset.md): shares the password page with invitations.
* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md) and [Profile and settings](https://docs.snapfix.com/product/features/account/profile.md): what a new person does after the link, such as verifying a contact.
* [Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md): the sites a person can use once they have joined.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): the push that tells site admins about a new active person.

## Edge cases

* **Offline:** the link is read from the server, so it cannot be opened offline. The apps check for a connection before they send a password ([Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md#states)).
* **Unknown or missing link:** "invalid reference" or "Something went wrong" in an alert, then sign-in ([Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md#states)).
* **Used QR link:** a QR link that a sign-up has already used reports "invitation expired" to every caller. The web shows "Something went wrong".
* **Account already exists:** the QR sign-up refuses an email or phone number that already has an account.
* **Missing permission:** a signed-in web user who opens the password page is sent to Fix ([Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md#states)).
* **Several sites:** a person can belong to several sites. The new site appears after the prompt, and switching is in [Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md).
* **Time zones:** None.
* **Integrations:** None.


---

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