> 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/engineering-reference/api/onboarding.md).

# Onboarding API

{% 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/spec/api/onboarding.md).
{% endhint %}

Setting up a new site from templates, the web onboarding form, and the pre-registration survey.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/guest`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`; `authpy` at `https://z3.snapfix.com`
* **Auth:** api\_php\_live\_v2 (`/v1/guest`): one shared HTTP Basic login for every route, which is also in public web bundles. The guest group also runs the blacklist, the shared rate limiter, and limits of 60 calls a minute and 1,000 a day ([blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)). The setup link's ID is the only other check on the setup routes. php-apis: a user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]), with no role check. The create-site and copy actions act on the user named in the body, not the token's user; [`new_site_status`](#get-actionnew_site_status) reads the user from the token. `webcust_list_templates` takes HTTP Basic with `AUTH_USERNAME` instead of a token \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. authpy: the apps' shared HTTP Basic login.
* **Used by:** web\_app\_v2, iOS, Android, webadmin\_angular, web\_onboarding\_form, authpy; 7 of the 19 endpoints have no known caller
* **Methods on php-apis:** the dispatchers accept any HTTP method except `OPTIONS`; the table lists the method the clients send. Shared conventions (envelopes, status codes, token errors) are in [README.md](https://docs.snapfix.com/engineering-reference/api.md).

| Method | Path                                                                                     | Service            | Purpose                                                                                                                                                                                   |
| ------ | ---------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/v1/guest/areas`                                                                        | api\_php\_live\_v2 | List the built-in area names (no caller)                                                                                                                                                  |
| GET    | [`/v1/guest/onboarding/{uuid}`](#get-v1guestonboardinguuid)                              | api\_php\_live\_v2 | Get the site details behind a setup link                                                                                                                                                  |
| POST   | [`/v1/guest/onboarding/{uuid}`](#post-v1guestonboardinguuid)                             | api\_php\_live\_v2 | Submit the setup form and queue the site setup                                                                                                                                            |
| GET    | `/v1/guest/parent/paying-customers`                                                      | api\_php\_live\_v2 | List paying customers; optional query `country`, two letters (no caller) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] |
| GET    | [`/v1/guest/survey/prereg`](#get-v1guestsurveyprereg)                                    | api\_php\_live\_v2 | Get the pre-registration survey                                                                                                                                                           |
| POST   | [`/v1/guest/survey/prereg`](#post-v1guestsurveyprereg)                                   | api\_php\_live\_v2 | Save pre-registration survey answers or a dismissal                                                                                                                                       |
| POST   | [`?action=create_parent_with_templates`](#post-actioncreate_parent_with_templates)       | php-apis           | Complete a new user's site, with template groups                                                                                                                                          |
| POST   | [`?action=create_parent_without_templates`](#post-actioncreate_parent_without_templates) | php-apis           | Complete a new user's site, and email the Snapfix team                                                                                                                                    |
| ANY    | `?action=create_pri_onboard`                                                             | php-apis           | Create `tPub_Onboard` rows, generic table action (no caller) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]             |
| ANY    | `?action=delete_pri_onboard`                                                             | php-apis           | Delete `tPub_Onboard` rows, generic table action (no caller) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]             |
| POST   | [`?action=list_industries_roles_templates`](#post-actionlist_industries_roles_templates) | php-apis           | List industries, roles and templates for a new site                                                                                                                                       |
| ANY    | `?action=modify_pri_onboard`                                                             | php-apis           | Change `tPub_Onboard` rows, generic table action (no caller) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]             |
| GET    | [`?action=new_site_status`](#get-actionnew_site_status)                                  | php-apis           | List sites a user was just added to, once                                                                                                                                                 |
| ANY    | `?action=read_pri_onboard`                                                               | php-apis           | Read `tPub_Onboard` rows by UUID, generic table action (no caller) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]       |
| ANY    | `?action=save_pri_onboard`                                                               | php-apis           | Save `tPub_Onboard` rows (no caller) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]                                     |
| POST   | [`?action=webcust_clone_template`](#post-actionwebcust_clone_template)                   | php-apis web       | Copy a group, with its tasks, into a site                                                                                                                                                 |
| POST   | [`?action=webcust_list_templates`](#post-actionwebcust_list_templates)                   | php-apis web       | List group templates \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]                                                |
| POST   | [`?action=webcust_list_templates_jwt`](#post-actionwebcust_list_templates_jwt)           | php-apis web       | List group templates, with a user token                                                                                                                                                   |
| GET    | [`/webcust-list-templates`](#get-webcust-list-templates)                                 | authpy             | List group templates, from php-apis                                                                                                                                                       |

The five `*_pri_onboard` actions work on `tPub_Onboard`, the onboarding-status lookup table. They are listed in the iOS and Android endpoint catalogs, but no code calls them \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].

## GET /v1/guest/onboarding/{uuid}

Returns the account details of a setup link, which the setup form uses to fill in its first step.

* **Auth:** the guest login. The link's ID in the path is the only other check: anyone with the login and the ID can read the site's name, logo and address. Only setups that aren't finished are returned.
* **Used by:** web\_onboarding\_form, when the setup page opens.

**Request**

| Name   | In   | Type   | Required | Rules                                                                                                                                                                    |
| ------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid` | path | string | yes      | The setup link's ID: a [`tPri_Org_OnboardingLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_onboardinglog.md) row whose `fOnboardingTs` is empty |

No body and no query parameters.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "name": "Example Lodge",
    "logo": null,
    "address": "1 Example Road",
    "postalCode": "12345",
    "city": "Springfield",
    "state": "",
    "countryCode": "IE",
    "groupTemplates": [
      { "uuid": "123", "name": "Housekeeping", "image": null, "sortOrder": 1 }
    ]
  }
}
```

* `name` and `logo`: the site's name and logo URL, or `null`.
* `address`, `postalCode`, `city`, `state` and `countryCode`: the site's newest basic address; all `null` when the site has none. `countryCode` is a two-letter country code.
* `groupTemplates`: the groups, among the 28 template IDs built into the code, that exist and aren't deleted. Each has `uuid`, `name`, `image` and `sortOrder`. It doesn't depend on the setup record.

The setup form fills in `name`, `address`, `state`, `postalCode`, `city`, `countryCode` and `logo`. It doesn't read `groupTemplates` \[[ASK-40](https://github.com/snapfix/docs/blob/main/ASK.md#ask-40-should-the-setup-form-offer-group-templates)].

**Errors:** `401` `{"error": "Unauthorized."}` without the guest login (not the usual envelope). `404` "Resource not found" for an unknown link, a finished setup, or a site that can't be loaded. `400` with a reference code for a blacklisted caller, and `429` over a limit ([blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).

**Side effects:** none.

## POST /v1/guest/onboarding/{uuid}

Checks the setup form's file, then queues the job that sets up the site, its groups, its users and their invitations.

* **Auth:** the guest login. The link's ID must belong to an unfinished setup. That check runs after the file is checked.
* **Used by:** web\_onboarding\_form, on "CREATE ACCOUNT", the last step of the form.

**Request** (`multipart/form-data`)

| Name   | In   | Type   | Required | Rules                                                                                 |
| ------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `uuid` | path | string | yes      | The setup link's ID, as for the GET                                                   |
| `data` | body | file   | yes      | A `.json` file of up to 2048 KB, with the keys below. Only the first admin is checked |
| `logo` | body | file   | no       | jpg, jpeg, png or gif, up to 2048 KB; becomes the site's logo                         |

The keys of `data`:

| Key              | Type              | Rules and use                                                                                                                                                                                                                                                                                       |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account`        | object            | `name`, `address1`, `address2`, `state`, `postalCode`, `city` and `country` (two-letter code). Not checked on submit; the setup job reads them to name and address the site, and fails if they are missing                                                                                          |
| `admins`         | array             | Each has `firstname`, `lastname`, `email`, `countryCode` and `mobile`. The first is the owner: `email` must be a valid address, and `countryCode` and `mobile` must be present and numeric. A mobile number that an active user already has is refused, unless an active user has the owner's email |
| `users`          | array             | Same fields. A user whose email is given but isn't valid is skipped                                                                                                                                                                                                                                 |
| `tags`           | array of strings  | The locations from step 4. The setup job doesn't save them                                                                                                                                                                                                                                          |
| `groups`         | object            | Optional. `templateUuids` lists IDs of groups to copy; any group ID is accepted. `names` lists group names, used only without `templateUuids`. The form doesn't send `groups`                                                                                                                       |
| `rooms`, `areas` | arrays of strings | Optional. Created in the site's default building. The form doesn't send them                                                                                                                                                                                                                        |

The form allows up to 10 admins, 100 users and 1,000 tags; the server enforces no count.

```json
{
  "account": {
    "name": "Example Lodge",
    "address1": "1 Example Road",
    "address2": "",
    "state": "",
    "postalCode": "12345",
    "city": "Springfield",
    "country": "IE"
  },
  "admins": [
    { "firstname": "Jane", "lastname": "Smith", "email": "jane@example.com", "countryCode": "44", "mobile": "7700900123" }
  ],
  "users": [],
  "tags": ["Room 101", "Room 102"]
}
```

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": null
}
```

The response means the file passed the checks. The site isn't ready until the job finishes, and the setup is marked finished only then.

**Errors:** `401` `{"error": "Unauthorized."}` without the guest login. `422` with the first failed check, for example:

```json
{
  "status": "error",
  "message": "Admin email address is not valid"
}
```

Other messages: "The data field is required.", "Admin mobile number is not valid", "Country code and mobile should be integers.", and "It appears this mobile number is already in use by another user. Please contact Snapfix (<support@snapfix.com>) if this is your number." The file is checked before the link, so these messages come back even for an unknown link. A `data` file whose contents aren't a JSON object fails inside the check with a server error, not one of these messages. `404` "Resource not found" for an unknown link or a finished setup, but only after the file passes. `400` and `429` as for the GET.

**Side effects:**

* Stores the logo under `img/` and the whole `data` file, with everyone's names, emails and mobile numbers, under `doc/` in file storage. Neither is deleted, and nothing reads the data file back.
* Dispatches the `Onboarding` job with the parsed file. With the default `sync` queue connection the job runs before the response; with a real queue it runs after it.
* The job then:
  * takes the first admin as the owner: an existing user with that email, or a new one; links the owner to the site as an admin ([`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md));
  * creates the groups in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md): one per ID in `groups.templateUuids` (a copy of that group's row), or one per name in `groups.names`, or, with neither, one group named "Maintenance". A name that is taken gets a space and a number ("Maintenance 1"). The form sends neither, so a site set up from the form gets one "Maintenance" group;
  * copies the settings, statuses and sub-statuses of the built-in blank template onto every new group, whichever way it was made ([`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md), [`tPri_Status`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_status.md), [`tPri_StatusSub`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_statussub.md)). No tasks are copied, and tag copying is switched off in the code;
  * makes the owner an admin of each group ([`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md));
  * sets the site's name, country, address and logo ([`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)), and adds a basic address ([`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md), [`tPri_ParentAddress`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentaddress.md));
  * creates a default building when `rooms` or `areas` has names, then the rooms and areas it doesn't have yet ([`tPri_Building`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_building.md), [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md), [`tPri_Area`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_area.md));
  * for each other admin and user: finds them by email, then by mobile number, or creates them; skips them when the email and the mobile number belong to two different users. Each is linked to the site as a user, also those listed in `admins`, and to every new group as an admin (from `admins`) or a user (from `users`);
  * creates new users with the origin onboarding, no password, the temporary-password flag set, verification required, and the email and mobile number unverified;
  * creates invitation links ([`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md), [`dynamiclink_invitation`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_invitation.md), [`dynamiclink_user`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_user.md)): one link per other admin and user, with one invitation per new group, and an invitation row with the status `exist` for a person who has signed in before, so the "added to a new site" prompt shows through [new\_site\_status](#get-actionnew_site_status). The owner's invitation row points at a second link that has no invitations, so an owner who has signed in before never gets that prompt; the link that holds the owner's invitations is never sent \[[ASK-62](https://github.com/snapfix/docs/blob/main/ASK.md#ask-62-should-an-existing-owner-see-the-added-to-a-new-site-prompt-after-a-setup)];
  * emails the link to each person who has never signed in, the owner included (`onboard_owner_email` for the owner, `onboard_email` for the rest). Each of those people other than the owner with a mobile number also gets it by WhatsApp, when an onboarding template is set up, or else by SMS. The owner gets no SMS;
  * marks the setup finished (`fOnboardingTs` in [`tPri_Org_OnboardingLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_onboardinglog.md)), after which the link answers `404`.
* People the job skips get no message, and the answer was already a success.
* Nothing claims the setup before the job finishes: a second submit with the same link, sent before then or after a failed job, is accepted and runs the setup again.

## GET /v1/guest/survey/prereg

Returns the pre-registration survey that applies to the caller's country and device, and logs the view.

* **Auth:** the guest login. No sign-in.
* **Used by:** iOS, on the sign-in screen while the first-launch survey is pending. Android, on the sign-in screen until the survey has been shown. web\_app\_v2 calls it only from a sign-up page that has no route, so the web isn't counted.

**Request**

No body. The caller's country comes from the IP lookup that the blacklist step adds to the request.

| Name          | In     | Type   | Required | Rules                                                                  |
| ------------- | ------ | ------ | -------- | ---------------------------------------------------------------------- |
| `device-type` | header | string | no       | `web`, `ios` or `android`. Without it, the device filter isn't applied |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "123",
    "dynamicFormJson": { "page_form": { "title": "A few questions", "components": [] } },
    "startTs": 1794387600000,
    "endTs": 1797066000000,
    "ipFilterJson": { "countryCode": ["IE"] },
    "deviceType": ["ios"],
    "inActive": 0,
    "createdTs": "2026-11-01T09:00:00Z",
    "modifiedTs": null,
    "createdByUserUuid": "admin",
    "modifiedByUserUuid": "admin"
  }
}
```

* Only surveys that aren't switched off (`fInActive` 0) and whose start and end times include the current time are considered.
* The survey's country list must contain the caller's country or be empty. When `device-type` is sent, the device list must contain it, be empty, or be `null`.
* A survey with a country list comes before one without. Among those, the newest comes first.
* `startTs` and `endTs` are milliseconds. `createdTs` and `modifiedTs` are ISO 8601, or `null` when not set.
* `data` is `null` when no survey applies.

**Errors:** `401` `{"error": "Unauthorized."}` without the guest login; `400` and `429` as for [GET /v1/guest/onboarding/{uuid}](#get-v1guestonboardinguuid).

**Side effects:** writes one row to [`tPri_Log_PreRegSurvey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_preregsurvey.md) on every call, also when no survey applies: the survey's ID or `null`, the HTTP method, the caller's IP address and its lookup details, and `admin` as creator and modifier.

## POST /v1/guest/survey/prereg

Saves a caller's answers to a pre-registration survey, or records that the survey was dismissed.

* **Auth:** the guest login. The survey ID is not tied to the caller.
* **Used by:** iOS and Android, from the survey screen (submit, cancel or close). The web isn't counted (see the GET).

**Request** (JSON)

| Name            | In   | Type    | Required | Rules                                                                                                                                                                                           |
| --------------- | ---- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`          | body | string  | yes      | A survey that exists; it needn't be running. An unknown ID returns `404`                                                                                                                        |
| `surveyDismiss` | body | integer | yes      | `0` submitted, `1` cancelled, `2` closed                                                                                                                                                        |
| `surveyJson`    | body | object  | yes      | The answers, as `{ "page_form": … }` mirroring the survey's `dynamicFormJson`. Stored as sent; nothing checks them against the questions. A key named `metadata` replaces the server's metadata |

```json
{
  "uuid": "123",
  "surveyDismiss": 0,
  "surveyJson": { "page_form": { "title": "A few questions", "components": [] } }
}
```

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": null
}
```

**Errors:** `422` with the first failed rule, for example "The uuid field is required."; `404` "Resource not found" for an unknown survey ID; `401` `{"error": "Unauthorized."}` without the guest login; `400` and `429` as for the GET.

**Side effects:** writes one row to [`tPri_Log_PreRegSurvey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_preregsurvey.md) with the answers, the dismiss state, the survey's ID, the HTTP method, the caller's IP address and lookup details, and `admin` as creator and modifier. The stored answers get a `metadata` key: the IP address, the `device-id` header, and the survey's start and end times.

## POST ?action=create\_parent\_with\_templates

Completes the site that a new user's sign-up created: sets its name, notes and view preference, and copies the chosen template groups into it. It doesn't add a site.

* **Auth:** a user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). Any signed-in user can call it. The site that changes is the sign-up site of the user named in `user_uuid`, not the caller's.
* **Used by:** iOS, at the end of the post-registration flow. Android, on the setup screen of the not-invited user flow.

**Request** (JSON)

| Name                       | In   | Type             | Required | Rules                                                                                                                                  |
| -------------------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`                | body | string           | yes      | The user whose sign-up site changes. The user must be in exactly one site whose `reg_secondary_fName` is `self`                        |
| `parent_name`              | body | string           | yes      | The site name, trimmed. It replaces the site's name only when no live site has it                                                      |
| `industry_uuid`            | body | string           | yes      | A live row of [`reg_industry`](https://docs.snapfix.com/engineering-reference/db/tables/reg_industry.md)                               |
| `industry_role_uuid`       | body | string           | yes      | A live role of that industry in [`reg_industry_roles`](https://docs.snapfix.com/engineering-reference/db/tables/reg_industry_roles.md) |
| `industry_template_uuids`  | body | array of strings | yes      | At least one. Every ID must be a live template group of that industry                                                                  |
| `reg_task_view_preference` | body | string           | yes      | `grid` or `list`                                                                                                                       |

```json
{
  "user_uuid": "123",
  "parent_name": "Example Lodge",
  "industry_uuid": "124",
  "industry_role_uuid": "125",
  "industry_template_uuids": ["126", "127"],
  "reg_task_view_preference": "grid"
}
```

**Response** `200`. The answer is the data of the user named in `user_uuid`, not only the new site:

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Parent": [ { "uuid": "123", "fName": "Example Lodge" } ],
    "tPri_Business": [ { "uuid": "128", "fName": "Housekeeping" } ],
    "tPri_Job": [ { "uuid": "129" } ]
  },
  "serverTs": 1794387600000
}
```

`data` is a [table data object](https://docs.snapfix.com/engineering-reference/api/tasks.md#table-data-object-php-apis) read from scratch (`last_updated_ts` 0) for `tPub_UserType`, `tPub_Onboard`, `tPri_Status`, `tPri_StatusSub`, `tPri_NotificationGlobal`, `tPri_NotificationBusiness`, `tPri_User`, `tPri_Business`, `tPri_UserBusiness`, `tPri_Parent`, `tPri_SettingsBusiness`, `tPri_Tag`, `tPri_TagHeader`, `tPri_Job`, `tPri_JobTag`, `tPri_JobUser`, `tPri_JobChat`, `tPri_JobTodo` and `tPri_JobNotif`, as in [`read_data`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionread_data). When that read succeeds, `tPri_Log_UserGdpr` holds the user's latest live consent row. Nothing is paged.

**Errors:** `200` with `result: false` and a message: "Data cannot be blank!" (empty body), "invalid user", "invalid parent\_name", "invalid industry", "invalid industry role", "invalid industry template selection" (missing or empty list), "invalid view preference", "invalid industry!", "invalid industry role!", "invalid industry templates!", "invalid parent data to update!" (the user has no sign-up site, or more than one), or "failed to update business data". Token errors are in [README.md](https://docs.snapfix.com/engineering-reference/api.md).

**Side effects:**

* Updates the sign-up site in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md): `reg_notes` (the industry, role and chosen templates), `reg_task_view_preference`, the modified time and `uuid_tUser_ModifiedBy`. When the name is free, `fName` becomes it and `reg_secondary_fName` gets the old name. When the name is taken, `fName` stays as it was and `reg_secondary_fName` is cleared. Either way the site is no longer marked `self`, so a second call for the same user fails with "invalid parent data to update!".
* Logs one site event to the time-series service.
* Copies each chosen template group into the site, as [webcust\_clone\_template](#post-actionwebcust_clone_template) does, without the source chats.
* Sets the user's `fRegData` in [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) to the typed name, also when the site didn't take it.
* Sends no email or SMS.

## POST ?action=create\_parent\_without\_templates

Completes the site that a new user's sign-up created, without template groups, and emails the details to the Snapfix team.

* **Auth:** as for [create\_parent\_with\_templates](#post-actioncreate_parent_with_templates).
* **Used by:** iOS, at the end of the post-registration flow when no template is chosen, and on the "joining a company" path. Android, on the same setup screen.

**Request** (JSON)

| Name                       | In   | Type    | Required | Rules                                                                                               |
| -------------------------- | ---- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| `user_uuid`                | body | string  | yes      | As for [create\_parent\_with\_templates](#post-actioncreate_parent_with_templates)                  |
| `parent_name`              | body | string  | yes      | The site name, trimmed. It replaces the site's name only when no live site has it                   |
| `industry_uuid`            | body | string  | yes      | A live industry                                                                                     |
| `industry_role_uuid`       | body | string  | yes      | A live role of that industry                                                                        |
| `reg_task_view_preference` | body | string  | yes      | `grid` or `list`                                                                                    |
| `notes`                    | body | string  | no       | Free text. Kept in `reg_notes` and sent to the team. iOS sends "joining a company" on the join path |
| `notify_snapfix_team`      | body | integer | no       | `1` asks the team to get in touch (opt-in). Any other value stores `0`                              |

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "data": {
    "tPri_Parent": [ { "uuid": "123", "fName": "Example Lodge", "reg_contact_snapfix": 0 } ]
  },
  "serverTs": 1794387600000
}
```

The `tPri_Parent` value is the site's full row after the update; unlike the with-templates action, there is nothing else in `data`. With the opt-in, the message is "Thanks, Our representative will contact you shortly and help you setting up your business on SnapFix to get things done".

**Errors:** `200` with `result: false` and a message, as for [create\_parent\_with\_templates](#post-actioncreate_parent_with_templates), without the template messages.

**Side effects:**

* Updates the sign-up site in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) as the with-templates action does, with `templates_selected` 0 in `reg_notes`, the notes, and `reg_contact_snapfix`. The same name rule and the same one-call limit apply.
* Logs one site event to the time-series service.
* Emails `register@snapfix.com` on every call, whatever the opt-in answer, with the subject "Registration Help Request : " and the site name. The body has the user's name, email and phone number, the site name, the industry and role, the notes, and "Opt-in" `YES` or `NO` \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].
* When the typed name is already a live site, and the server runs in live mode, the user's HubSpot contact is updated and marked "Joined Existing Parent". The user is not added to that site.
* Sets the user's `fRegData` in [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) to the typed name.

## POST ?action=list\_industries\_roles\_templates

Lists the industries, with their roles and template groups, for the sign-up steps that choose an industry, a role and work types.

* **Auth:** a user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). Any signed-in user can call it; the list is the same for everyone. No user is named in the request.
* **Used by:** iOS, when the industry screen loads. Android, in the not-invited user flow.

**Request**

No body; both apps post an empty one.

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "industry_uuid": "123",
      "industry_name": "Hospitality",
      "industry_sort_order": 1,
      "roles": [ { "uuid": "124", "fName": "Owner", "sort_order": 1 } ],
      "templates": [ { "template_uuid": "125", "template_name": "Housekeeping", "template_image": null, "template_sort_order": 1 } ]
    }
  ],
  "serverTs": 1794387600000
}
```

* Live industries from [`reg_industry`](https://docs.snapfix.com/engineering-reference/db/tables/reg_industry.md), sorted by sort order, then name. Roles come from [`reg_industry_roles`](https://docs.snapfix.com/engineering-reference/db/tables/reg_industry_roles.md) and templates from [`reg_industry_business_templates`](https://docs.snapfix.com/engineering-reference/db/tables/reg_industry_business_templates.md) joined to their live group in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md), sorted the same way.
* `roles` and `templates` appear only when the industry has some. Nothing is paged.

**Errors:** a database failure answers `200` with `result: false` and the error text. Token errors are in [README.md](https://docs.snapfix.com/engineering-reference/api.md).

**Side effects:** none.

## GET ?action=new\_site\_status

Lists the sites that the signed-in user was added to and hasn't been told about yet, and marks them as seen, so each site is listed once.

* **Auth:** a user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The user comes from the token's `identity` (or `sub`) claim, read without checking the signature; the dispatcher checks it only when `JWT_AUTH_ENABLED` is on. No user is named in the request.
* **Used by:** web\_app\_v2, in the side menu, once per page load after the account list loads; the site-access dialog opens when there are sites. iOS, after the site data loads and after an invitation link opens; the "added to new site" sheet opens. Android, when the group list loads a site.

**Request**

No body.

**Response** `200`

```json
{
  "result": true,
  "message": "SUCCESS",
  "data": [
    { "siteUUID": "123", "siteName": "Example Lodge", "siteImage": null, "userSiteCreatedTs": 1794387600000 }
  ],
  "serverTs": 1794387600000
}
```

* One item per site, from the user's live invitation rows in [`dynamiclink_user`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_user.md) with the status `exist` (people who already had an account, such as those added by a setup) and `welcome_status` 0, whose invitation in [`dynamiclink_invitation`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_invitation.md) and site aren't deleted. `userSiteCreatedTs` is when the invitation row was created.
* With none, the answer is `result: false` with the message "no new sites found" (HTTP `200`).

**Errors:** `200` with `result: false` and "invalid access!" when the token has no usable user. Token errors are in [README.md](https://docs.snapfix.com/engineering-reference/api.md).

**Side effects:** sets `welcome_status` to 1, the modified time and `uuid_tUser_ModifiedBy` on every matching invitation row, also rows hidden as a second row for the same site, so the next call doesn't list them. This happens before the client shows anything, so a lost response means the notice is never shown. A GET that writes data.

## POST ?action=webcust\_clone\_template

Copies a group, with its settings, statuses and tasks, into a site, and makes the user named in the body an admin of the copy.

* **Auth:** a user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). Any signed-in user can call it. The action doesn't check that the caller can use the source group or the destination site, and it works for the user named in `user_uuid`, not the caller.
* **Used by:** iOS, from the groups screen and the first-group guide. Android, when a group is created from a template.

**Request** (JSON)

| Name                | In   | Type   | Required | Rules                                                                                                                                                                                |
| ------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user_uuid`         | body | string | yes      | An existing user; becomes the creator and an admin of the new group                                                                                                                  |
| `template_uuid`     | body | string | yes      | The group to copy. Any group ID is accepted, not only a template                                                                                                                     |
| `parent_uuid`       | body | string | yes      | The site to copy into. Any site ID is accepted                                                                                                                                       |
| `new_business_name` | body | string | no       | The new group's name, when not empty. Otherwise the source group's name                                                                                                              |
| `enum_BusinessType` | body | string | no       | `task` (default) or `asset`; any other value means `task`. An asset group gets the asset guide text, its name as its address, and the default asset attributes. Neither app sends it |

```json
{
  "user_uuid": "123",
  "template_uuid": "124",
  "parent_uuid": "125",
  "new_business_name": "Housekeeping",
  "enum_BusinessType": "task"
}
```

**Response** `200`

```json
{
  "result": true,
  "message": "Success",
  "data": {
    "id": 123,
    "business_uuid": "126",
    "business_name": "Housekeeping",
    "business_address": "1 Example Road",
    "parent_name": "Example Lodge",
    "fImage": null,
    "fModifiedTs": 1794387600000,
    "red": 3,
    "amber": 1,
    "green": 0
  },
  "serverTs": 1794387600000
}
```

`red`, `amber` and `green` count the new group's tasks that aren't deleted, archived ones included, in each colour (`0` when there are none).

**Errors:** `200` with `result: false`. "Data cannot be blank!" for an empty body. The message names the missing fields, for example "user\_uuid, template\_uuid must be mentioned in the request!". The copy can also return "invalid user", "invalid parent", "invalid business" (the source group doesn't exist), "invalid business settings" (the source group has no settings) or "invalid parameters". Token errors are in [README.md](https://docs.snapfix.com/engineering-reference/api.md).

**Side effects:**

* Creates the group in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) in the destination site, with copies of the source's settings, statuses, sub-statuses, tag rules ([`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md)) and checklist permissions ([`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md)).
* Makes `user_uuid` an admin of the new group ([`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md)).
* Copies the source group's tasks that aren't archived or deleted and whose task time isn't in the future into [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), with their reminders, rooms, areas, users, tags, to-dos and assignees. Each copied task gets one "Snapfix Created The Task" chat line; the source's chats aren't copied.
* Adds the people assigned to the copied tasks to the new group, with their membership rows copied from the source group.
* The step that should move the source group's tag folders up to the site uses an undefined variable, so it changes no row.
* Adds to the site's group, user and task counts in Firebase, queues a sync entry per new row when `WEB_QUEUE_SUPPORT` is on, and sends an API update push through apipy when a queue setting is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST ?action=webcust\_list\_templates

Lists the group templates. The web app reaches the same list through the authpy route below.

* **Auth:** HTTP Basic with `AUTH_USERNAME`, the php-apis login, and no token \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The action is on the web dispatcher's list of actions that take Basic instead of a token. authpy calls it with its own php-apis login.
* **Used by:** authpy. Its `GET /webcust-list-templates` forwards the call here. No app or web client calls this action directly.

**Request**

No body is needed. authpy sends `POST` with a JSON body that carries the caller's IP address (`SP_FORWARDED_FOR`); the action ignores the rest.

**Response** `200`

```json
{
  "result": true,
  "message": "Success",
  "data": [
    { "uuid": "123", "fName": "Housekeeping", "fImage": null, "sort_order": 1 }
  ],
  "serverTs": 1794387600000
}
```

The `data` items are [group template objects](#group-template-object). With no templates, the answer is `{"result": false, "message": "Templates not found!"}`.

**Errors:** `200` with `result: false` and "You are not authorised to access this API." for a wrong or missing login.

**Side effects:** none.

## POST ?action=webcust\_list\_templates\_jwt

Lists the group templates for a signed-in user.

* **Auth:** a user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). Any signed-in user can call it; the token's user isn't used.
* **Used by:** iOS, in the first-group guide. Android, in the create-group screen. webadmin\_angular, on the Onboard Account page.

**Request**

No body is needed; Android sends an empty one.

**Response** `200`: the same as [webcust\_list\_templates](#post-actionwebcust_list_templates). The `data` items are [group template objects](#group-template-object).

**Errors:** `200` with `result: false` and "Templates not found!" when there are none. Token errors are in [README.md](https://docs.snapfix.com/engineering-reference/api.md).

**Side effects:** none.

## GET /webcust-list-templates

Lists the group templates through authpy, after it checks the apps' shared login, so the web app can show them in the create-group dialog.

* **Auth:** the apps' shared HTTP Basic login. A wrong or missing login gets `200` with `result: false` and the message "invalid authentication".
* **Used by:** web\_app\_v2, when the create-group dialog opens. The iOS call on the groups screen is commented out, and Android lists the URL in its endpoint catalog but calls the `_jwt` action instead.

**Request**

No body.

**Response** `200`: authpy returns the php-apis answer unchanged, `serverTs` included. The `data` items are [group template objects](#group-template-object).

```json
{
  "result": true,
  "message": "Success",
  "data": [
    { "uuid": "123", "fName": "Housekeeping", "fImage": null, "sort_order": 1 }
  ],
  "serverTs": 1794387600000
}
```

With a wrong or missing login:

```json
{
  "result": false,
  "message": "invalid authentication",
  "serverTs": 1794387600000
}
```

**Errors:** as above. php-apis errors pass through unchanged. A request without an `X-Forwarded-For` header fails inside authpy before php-apis is called.

**Side effects:** runs the IP block check, which logs the call, but ignores its result, so a blocked address still gets the list. Then posts to php-apis web `webcust_list_templates` with authpy's php-apis login and the caller's IP address in `SP_FORWARDED_FOR`.

## Group template object

| Field        | Type           | Meaning                   |
| ------------ | -------------- | ------------------------- |
| `uuid`       | string         | The template group's ID   |
| `fName`      | string         | The template group's name |
| `fImage`     | string or null | The image URL             |
| `sort_order` | integer        | The display order         |

The list holds the groups of the built-in template site (`uuid_tParent` `snapfix_templates`) that aren't deleted, sorted by display order, then by name.


---

# 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/engineering-reference/api/onboarding.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.
