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

# QR 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/qr.md).
{% endhint %}

QR forms and group QR codes, for reporting a problem by scanning a QR code without an account. A group has one standard QR form \[[ASK-74](https://github.com/snapfix/docs/blob/main/ASK.md#ask-74-can-a-groups-qr-code-be-removed-or-replaced)]. Scanning its code opens the public form, and a submit creates a task.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `authpy` at `https://z3.snapfix.com`. The production form page calls authpy at `z3.s6eur.com` (qr\_forms @ bdfc4f20a5, `src/environments/environment.prod.ts:4`) \[[ASK-8](https://github.com/snapfix/docs/blob/main/ASK.md#ask-8-confirm-the-environments)].
* **Auth:** api\_php\_live\_v2: user token (authpy JWT in `Authorization: Bearer`). The list needs the group's update rule, which any member who is not read-only passes; the create needs a group admin. php-apis: 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)]). `read_business_qr` and `generate_business_qr` take the user from the token's payload, whose signature only the dispatcher checks, and only while `JWT_AUTH_ENABLED` is on. `qr_task` is on the dispatcher's no-token list and needs only the php-apis Basic login (`AUTH_USERNAME`). authpy: no user login. The three `/qr-form` routes take the shared app Basic login, which also ships in qr\_forms; the form's ID is the only other check. The submit also needs a reCAPTCHA token.
* **Used by:** web\_app\_v2 (the group QR dialog: list and create), iOS and Android (the group QR screen: `read_business_qr`, and the Laravel create), qr\_forms (the public form: details, rooms and submit); 2 of the 8 endpoints have no known caller.
* **Answers and errors:** the api\_php\_live\_v2 envelope and the codes every `/v1/app` route can return are in [Tasks: common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors). php-apis and authpy answer HTTP `200` with `result` `false` and the message for their own errors ([Responses](https://docs.snapfix.com/engineering-reference/api.md#responses)). Each section lists its own errors.
* **Logs:** api\_php\_live\_v2 writes each call to its request log, with the response when it is under about 100 KB; php-apis stores each request body and each response under about 100 KB in its daily request log. authpy writes each form call, with its request fields, and its response when that is under about 100 KB, to the daily `apilog_YYYY_MM_DD` table. For submissions and detail reads it also writes a [`tPri_Log_API_IP_RateLimit`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_api_ip_ratelimit.md) row with the caller's IP address, which the submission limit counts (authpy @ 5d5758661c, `model/t_log_ip_blocked_v3.py:1543-1571`, `:1618-1640`).

| Method | Path                                                                          | Service            | Purpose                                                                                                                                       |
| ------ | ----------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | [`/v1/app/businesses/{businessUuid}/qr`](#get-v1appbusinessesbusinessuuidqr)  | api\_php\_live\_v2 | List a group's QR forms                                                                                                                       |
| POST   | [`/v1/app/businesses/{businessUuid}/qr`](#post-v1appbusinessesbusinessuuidqr) | api\_php\_live\_v2 | Create a QR form for a group \[[ASK-74](https://github.com/snapfix/docs/blob/main/ASK.md#ask-74-can-a-groups-qr-code-be-removed-or-replaced)] |
| ANY    | `?action=generate_business_qr`                                                | php-apis           | Generate a group's QR code (no caller)                                                                                                        |
| ANY    | `?action=qr_task`                                                             | php-apis           | Create a task from a QR code (no caller)                                                                                                      |
| POST   | [`?action=read_business_qr`](#post-actionread_business_qr)                    | php-apis           | List a group's QR codes                                                                                                                       |
| GET    | [`/qr-form/{uuid}`](#get-qr-formuuid)                                         | authpy             | Get a QR form                                                                                                                                 |
| POST   | [`/qr-form/{uuid}`](#post-qr-formuuid)                                        | authpy             | Submit a QR form, which creates a task                                                                                                        |
| GET    | [`/qr-form/{uuid}/rooms`](#get-qr-formuuidrooms)                              | authpy             | List a QR form's rooms                                                                                                                        |

Notes on the table:

* Rows marked "(no caller)" have no caller in any client clone. iOS and Android list `generate_business_qr` in their endpoint registries, but iOS never reads that name, and Android's entry for it points at the Laravel create route, which both apps call instead (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/APIEndPointUtils.java:422`). No client calls `qr_task`. Whether to remove both is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* What the uncalled actions can do: `generate_business_qr` creates the standard form for a group where the token's user is an admin, with its own copy of the default layout (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:38414-38493`). `qr_task` takes `business_uuid` and `title` and creates a task in any live group whose site has an email key. It acts as the site's email admin user: when the site has none, it finds or creates a service user and makes it that admin, and it adds that user to the group when needed. Base64 files in the request are written to disk and uploaded to S3 (`class.functions.php:23112-23300`).
* The php-apis dispatcher accepts any method except `OPTIONS` ([Requests](https://docs.snapfix.com/engineering-reference/api.md#requests)); the table shows `POST`, which both apps send for `read_business_qr`.
* `/v1/qr` has no routes: `routes/qr.php` holds only its header comment, so the `qr` route group, which sets up the `authorize`, `blacklist` and `rate.limiter` middleware, guards nothing (api\_php\_live\_v2 @ ef3c4319f6, `routes/qr.php:1-7`, `app/Providers/RouteServiceProvider.php:89-93`).

## How a scan becomes a task

```mermaid
sequenceDiagram
  participant Page as qr_forms page
  participant Auth as authpy
  participant Py as apipy
  participant Laravel as api_php_live_v2
  Page->>Auth: GET the form, with the shared Basic login
  Page->>Auth: GET the form's rooms
  Page->>Auth: POST the form fields and a reCAPTCHA token
  Auth->>Auth: Check the token, the form and the limits, then create the task
  Auth->>Py: Push to the group's admins and viewers
  Auth-->>Page: Task reference and share link
  Auth-->>Laravel: In the background, suggestions, then room, area, tags and assignees
```

The form's row stores its group and a default task, the job JSON. The submit copies the request's fields over that JSON, so a request can name another group. Each section below gives its route's own checks.

## Related routes

* **SDK group:** `GET` and `POST /v1/sdk/business/{businessUuid}/qr` run the same two group routes, where the caller names the user (api\_php\_live\_v2 @ ef3c4319f6, `routes/sdk.php:11`). Neither has a caller ([Open API](https://docs.snapfix.com/engineering-reference/api/open-api.md)).
* **Staff:** `GET` and `POST /v1/admin/qr-form`, and `PUT` and `DELETE /v1/admin/qr-form/{uuid}`, list, create, change and delete any group's forms (`routes/admin.php:167-172`). They are in [Staff](https://docs.snapfix.com/engineering-reference/api/staff.md).
* **Suggestions:** the public form asks `POST /v1/guest/suggestions/title` and `POST /v1/guest/suggestions/rooms` for its title and room suggestions, and the submit's background step asks the rooms, areas, tags and assignees routes ([AI](https://docs.snapfix.com/engineering-reference/api/ai.md)). That step then calls the `/v1/internal/tasks` routes ([Internal](https://docs.snapfix.com/engineering-reference/api/internal.md)).
* **Push:** `POST /req-to-notify-user-for-qr-job` on apipy is in [Notifications](https://docs.snapfix.com/engineering-reference/api/notifications.md).
* **Screens and features:** [Group QR codes](https://docs.snapfix.com/how-the-apps-work/screens/groups/qr-codes.md), which also says where the app screens open; the public [QR form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md); [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md).
* **Tables:** [`qr_formdata`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata.md) holds the forms, [`qr_formdata_log`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata_log.md) each accepted submission.

## GET /v1/app/businesses/{businessUuid}/qr

Lists a group's QR forms with their public links: the web's "Group QR Codes" dialog.

* **Auth:** user token. The caller must pass the group's update rule: an admin of the group, a holder of "view business settings", or a member who is not read-only (api\_php\_live\_v2 @ ef3c4319f6, `app/Policies/BusinessPolicy.php:82-93`, `app/Http/Controllers/v1/Versions/v1_0/App/QrFormController.php:35-39`). Anyone else, including a signed-in user who is not a member, gets `403` "Access denied". Which rule is intended is open \[[ASK-71](https://github.com/snapfix/docs/blob/main/ASK.md#ask-71-who-may-archive-or-delete-a-group-and-see-its-qr-codes)].
* **Used by:** web (`GroupHttpService.getGroupQRList`, when the group QR dialog opens: web\_app\_v2 @ 0989b8e685, `src/app/services/group/group-http/group-http.service.ts:191-204`, `src/app/pages/group-settings/group-settings-group-qr/group-settings-group-qr.component.ts:154-162`). iOS and Android list the codes through [`read_business_qr`](#post-actionread_business_qr) instead.

**Request**

| Name           | In   | Type   | Required | Rules                                              |
| -------------- | ---- | ------ | -------- | -------------------------------------------------- |
| `businessUuid` | path | string | yes      | The group. An unknown or deleted group gives `404` |

**Response** `200`: `data` is a list of [QR form objects](#qr-form-object), one per live form of the group, in database order. Only forms with no expiry, or with an expiry already past, are listed: a form whose expiry is still ahead is left out (`app/Services/QrFormService.php:27-37`, `QrFormController.php:41`). No code in the repos sets a form's expiry, and no form in the staging copy has one.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "6f1d2c9a-3b7e-4f05-8a2d-91c4e0b7d356",
      "url": "https://qr.example.com/6f1d2c9a-3b7e-4f05-8a2d-91c4e0b7d356",
      "posterTitle": "Standard",
      "posterHackerWarningDescription": "You will never be asked for a username or password",
      "posterHackerWarning": 1,
      "posterDescription": "This standard QR will ask the user for some basic details and create a task",
      "inAppTitle": "Standard",
      "formEnum": "basic_v2",
      "createdTs": "2026-11-14T09:00:00.000000Z",
      "modifiedTs": "2026-11-14T09:00:00.000000Z"
    }
  ]
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the rule above; `404` "Resource not found" for an unknown or deleted group.

**Side effects:** none.

## POST /v1/app/businesses/{businessUuid}/qr

Creates the group's standard QR form (`basic_v2`): the "Generate QR" action on all three platforms. A group has one standard form, the server refuses a second, and customers can neither remove nor replace it \[[ASK-74](https://github.com/snapfix/docs/blob/main/ASK.md#ask-74-can-a-groups-qr-code-be-removed-or-replaced)].

* **Auth:** user token. The caller must be an admin of the group (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/QrFormController.php:64-68`). A member who is not an admin gets `400`. A signed-in user who is not a member gets `403` with the untranslated key `messages.access_denied` (`app/Traits/Authenticated.php:20-31`).
* **Used by:** web (`GroupHttpService.createGroupQR`, from "Generate QR"; the web adds the new form to the list after 1.5 seconds: web\_app\_v2 @ 0989b8e685, `src/app/services/group/group-http/group-http.service.ts:206-213`, `src/app/pages/group-settings/group-settings-group-qr/group-settings-group-qr.component.ts:64-77`), iOS (`QRCodeListVC.generateQRIfNeeded`, from "Generate", through the registry name `generate_business_qr_laravel`: ios @ aa31967ac8, `SnapFix/QRCode/QRCodeListVC.swift:83-125`, `:202-204`, `:254-257`), Android (`QRGroupActivity.generateBusinessQR`: android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/QRGroupActivity.kt:169-199`, `app/src/main/java/gmail/com/snapfixapp/network/ApiService.java:386-388`).

**Request**

| Name           | In   | Type   | Required | Rules                                              |
| -------------- | ---- | ------ | -------- | -------------------------------------------------- |
| `businessUuid` | path | string | yes      | The group. An unknown or deleted group gives `404` |

The body is ignored. The web sends none, iOS sends `{}` and Android an empty string.

**Response** `200`: `data` is the new [QR form object](#qr-form-object). Its warning fields are `null`, because the row isn't read back after the insert; the stored row has the database defaults, which the list then shows.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "6f1d2c9a-3b7e-4f05-8a2d-91c4e0b7d356",
    "url": "https://qr.example.com/6f1d2c9a-3b7e-4f05-8a2d-91c4e0b7d356",
    "posterTitle": "Standard",
    "posterHackerWarningDescription": null,
    "posterHackerWarning": null,
    "posterDescription": "This standard QR will ask the user for some basic details and create a task",
    "inAppTitle": "Standard",
    "formEnum": "basic_v2",
    "createdTs": "2026-11-14T09:00:00.000000Z",
    "modifiedTs": "2026-11-14T09:00:00.000000Z"
  }
}
```

**Errors:**

* [Common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors).
* `400` "Only an administrator of a group can create a new QR for that group" for a member who is not an admin.
* `400` "Default QR for this group already exists!" when the group has a live standard form with no expiry. The query's `OR` is not grouped, so the same answer goes to every group while any live form, in any group, has an expiry set (`app/Services/QrFormService.php:43-50`, `QrFormController.php:70-72`).
* `403` `messages.access_denied` for a signed-in user who is not a member.
* `404` "Resource not found" for an unknown or deleted group.

**Side effects:** inserts one [`qr_formdata`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata.md) row: type `basic_v2`, visible in the app, "Standard" as its in-app and poster title, "This standard QR will ask the user for some basic details and create a task" as its poster text, no expiry, the default layout (`resources/other/dynamicQrForm.php`), and a job JSON for this group that names the "Snapbot QR" user business as the creator (`QrFormController.php:74-85`, `resources/schemas/hardCodedJob.schema.v1.php:15-44`). With `VIA_QUEUE` on, the insert also logs a queue entry (`app/Providers/EventServiceProvider.php:117`, `app/Observers/QueueObserver.php:18-23`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. No task, push or email.

## POST ?action=read\_business\_qr

Lists a group's QR forms for the iOS and Android group QR screens. It reads the same table as the Laravel list, with a different filter.

* **Auth:** user token. The user comes from the token's payload; "invalid access!" when there is none (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:38349-38352`, `:27295-27343`). The caller must have a live, unblocked admin row for the group's site, or a live membership of the group with the admin role; any other member gets "invalid business" (`:38369-38383`). The web list is wider: any member who is not read-only sees it. Which rule is intended is open \[[ASK-71](https://github.com/snapfix/docs/blob/main/ASK.md#ask-71-who-may-archive-or-delete-a-group-and-see-its-qr-codes)].
* **Used by:** iOS (`QRCodeListVC.getOrGenerateQRCodeList`, when the screen opens: ios @ aa31967ac8, `SnapFix/QRCode/QRCodeListVC.swift:42`, `:83-125`) and Android (`QRGroupActivity.readQRCodeAPI`, when the screen opens and on pull to refresh: android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/QRGroupActivity.kt:77-78`, `:135-166`). Both send a JSON body by `POST`.

**Request** (JSON body)

| Name            | In   | Type   | Required | Rules                                         |
| --------------- | ---- | ------ | -------- | --------------------------------------------- |
| `business_uuid` | body | string | yes      | The group. Missing or empty: "invalid params" |

**Response** `200`: `data` lists the group's live forms with the database column names: `uuid`, `form_enum`, `in_app_title`, `poster_title`, `poster_description`, `poster_hacker_warning`, `poster_hacker_warning_description`, `fCreatedTs` and `fModifiedTs` in milliseconds, and `url` (see [QR form object](#qr-form-object)). The expiry filter compares the millisecond expiry with `NOW()*1000`, a far larger number, so every form passes and expired forms are listed too (`:38385-38392`).

* `url` is `https://qr.snapfix.com/<uuid>` on the live server and a test host otherwise (`:38400-38404`), the same host Laravel's links use in production ([notes/crawl/groups.md](https://github.com/snapfix/docs/blob/main/notes/crawl/groups.md#qr-dialog)).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [
    {
      "uuid": "6f1d2c9a-3b7e-4f05-8a2d-91c4e0b7d356",
      "form_enum": "basic_v2",
      "in_app_title": "Standard",
      "poster_title": "Standard",
      "poster_description": "This standard QR will ask the user for some basic details and create a task",
      "poster_hacker_warning": 1,
      "poster_hacker_warning_description": "You will never be asked for a username or password",
      "fCreatedTs": 1794387595000,
      "fModifiedTs": 1794387595000,
      "url": "https://qr.example.com/6f1d2c9a-3b7e-4f05-8a2d-91c4e0b7d356"
    }
  ]
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (empty body: php-apis @ 238ca4414e, `html/api/snapfix/index.php:1167-1174`); "invalid access!" (no user in the token); "invalid params" (no `business_uuid`); "invalid group" (unknown or deleted group); "invalid business" (the group's site is missing or deleted, or the caller is neither a site admin nor a group admin); "no data found" (no form to list). Token errors are in [User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens).

**Side effects:** none.

## GET /qr-form/{uuid}

Gets a scanned form: its type, its layout, its site, and whether the site has AI suggestions on. The public form page reads it first.

* **Auth:** the shared app Basic login; no user token, the token check is commented out (authpy @ 5d5758661c, `app.py:1415-1418`, `auth.py:22-30`). The form must exist, must not be deleted and must not be expired. Anyone with the login and a form ID gets these details, including the site's ID. The form's ID is the last part of the link in its QR code.
* **Used by:** qr\_forms (`FormService.getFormDetails`, when the page loads: qr\_forms @ bdfc4f20a5, `src/app/services/form/form.service.ts:28-32`, `src/app/pages/forms/forms.component.ts:142-179`).

**Request**

| Name   | In   | Type   | Required | Rules         |
| ------ | ---- | ------ | -------- | ------------- |
| `uuid` | path | string | yes      | The form's ID |

**Response** `200`: `data` is a [form details object](#form-details-object).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "type": "basic_v2",
    "form_schema": {
      "page_form": {
        "title": "Report issues, requests and feedback",
        "input_image_01": { "title": "1. What is it?", "hint": null },
        "input_text_01": { "title": "2. Where is it? *", "hint": "Exact location is important" },
        "input_text_02": { "title": "3. Notes & contact information", "hint": " " },
        "submit_button_text": "Submit"
      },
      "page_success": { "title": "Thank you!", "text": "Issue submitted successfully" },
      "page_fail": { "title": "Something went wrong!", "repeat_button_text": "Try again" }
    },
    "parent_uuid": "0b8e4d71-5c2a-4e96-b3f0-7a1d9c6e2f48",
    "aiSuggestionEnabled": 1
  }
}
```

* The page shows any type other than `basic_v2`, `dropdown_v1` and `radiobutton_v1` as a custom form (`src/app/pages/forms/forms.component.ts:204-208`).
* The form's group is not checked: a form whose group was deleted still answers, and its submit then fails ([POST /qr-form/{uuid}](#post-qr-formuuid)).

**Errors:** `200` with `result` `false`: "invalid authentication" (the Basic login is missing or wrong); "invalid code" (unknown or deleted form); "code expired" (its expiry has passed); the abuse check's message when the caller is blocked ([Blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).

**Side effects:** no data change. The call and its answer are logged, with a rate-limit row (see **Logs** above).

## POST /qr-form/{uuid}

Submits a scanned form and creates a red task. The task goes to the group named in the form's job JSON, unless the request names another.

* **Auth:** the shared app Basic login; no user token. The body must also carry a reCAPTCHA v3 token that Google marks as successful; the server checks it with a secret written in the code (authpy @ 5d5758661c, `model/feature_qrform.py:143-159`, `model/utils.py:125-133`). Only `success` is read, not the score or the action. One fixed token value skips the Google call (`model/feature_qrform.py:152`).
* **Limits:** 50 submissions a minute per IP address, taken from the first `X-Forwarded-For` address \[[ASK-172](https://github.com/snapfix/docs/blob/main/ASK.md#ask-172-does-the-load-balancer-in-front-of-authpy-replace-or-append-x-forwarded-for)] (`model/t_log_ip_blocked_v3.py:301-317`, `:642-651`), and 50 created tasks a minute per form (`model/feature_qrform.py:185-199`). The two read routes have no rate limit.
* **Used by:** qr\_forms (`FormsComponent.submit`, through `FormService.saveForm`, as multipart form data: qr\_forms @ bdfc4f20a5, `src/app/pages/forms/forms.component.ts:84-124`, `src/app/services/form/form.service.ts:34-40`). The token is for the reCAPTCHA action `importantAction`, and the page leaves the token out when reCAPTCHA gives none (`forms.component.ts:87`, `:94`). The standard and custom layouts build the fields (`src/app/pages/forms/components/report-issues-form/report-issues-form.component.ts:115-140`, `src/app/pages/forms/components/dynamic-form/dynamic-form.component.ts:219-235`).

**Request** (form fields, multipart or urlencoded; the route reads form fields and files only, so a JSON body counts as empty and gets "invalid params")

| Name                | In   | Type             | Required                          | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------- | ---- | ---------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`              | path | string           | yes                               | The form                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `recaptcha_token`   | body | string           | yes                               | Missing or empty: "invalid authentication". Not successful at Google: "invalid recaptcha"                                                                                                                                                                                                                                                                                                                                                                                                            |
| `fTitle`            | body | string           | yes, unless the job JSON sets one | The task's title; the default job JSON's is empty. Empty: "invalid job title". No length limit on the server; the custom form allows 50 characters                                                                                                                                                                                                                                                                                                                                                   |
| `fDescription`      | body | string           | no                                | Stored as sent, with no length limit. Without it the task keeps the job JSON's description, "This task was generated from a QR Code"                                                                                                                                                                                                                                                                                                                                                                 |
| `uploaded_image`    | body | file             | one of three                      | The photo. Stored public-read in the image bucket under the file's own extension and content type, with no type or size check; its URL becomes the task's photo (`model/feature_qrform.py:252-254`, `s3helper.py:6-36`)                                                                                                                                                                                                                                                                              |
| `fImage`            | body | string           | one of three                      | An image URL, used as the photo when no file is sent                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `fLargeTextTitle`   | body | string           | one of three                      | Text shown in place of a photo, stored whenever it is sent, also next to a photo. The page sends the title here when there is no photo. With no photo, image URL or text: "invalid job image"                                                                                                                                                                                                                                                                                                        |
| `jobchats`          | body | JSON string      | no                                | A JSON list of chat items, added after the job JSON's own items. Each item's `fText`, `uuid_tChatItemType`, `fFileUrl`, `fThumbnailUrl` and `fUserBusinessName` is stored as sent. Text that is not JSON gives the parser's message                                                                                                                                                                                                                                                                  |
| `roomUUIDs[]`       | body | array of strings | no                                | Also read as `roomUUIDs`, `roomUuid` and `roomUuid[]`. Only the first room is added, by the background step, and only when it is in the group's site (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/RoomService.php:736-744`)                                                                                                                                                                                                                                                                       |
| `guest_email`       | body | string           | no                                | Must match one plain address pattern, or "Email is invalid". Used only when the form turns on shareable links                                                                                                                                                                                                                                                                                                                                                                                        |
| `fLat`, `fLng`      | body | number           | no                                | The location, stored on the task; `lat` and `lng` are read too. The page sends `0` when the browser gives none                                                                                                                                                                                                                                                                                                                                                                                       |
| `imageRef`          | body | string           | no                                | Also read as `image_ref`. The image reference from the title suggestion, for the background step                                                                                                                                                                                                                                                                                                                                                                                                     |
| `aiTitle`           | body | string           | no                                | The suggested title, logged in `log_ai_job`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `aiTitleSuggestion` | body | `0` or `1`       | no                                | Stored as the task's `title_aiSuggested`, and only while the title equals `aiTitle` (`model/feature_qrform.py:441-449`)                                                                                                                                                                                                                                                                                                                                                                              |
| `aiRoomSuggestion`  | body | `0` or `1`       | no                                | Marks the submitted room as AI-suggested. The live page's standard and custom forms send `1` when the submitted room is the one the suggestion chose, else `0` (qr\_forms @ 31d98f7, branch `fix/ai-task-creation-photo-capture-image-issue`, `report-issues-form.component.ts` and `dynamic-form.component.ts`); master at bdfc4f20a5 does not send it \[[ASK-226](https://github.com/snapfix/docs/blob/main/ASK.md#ask-226-should-master-and-syncyml-follow-the-branch-that-runs-on-qrsnapfixcom)] |
| any other field     | body | string           | no                                | Replaces the job JSON's value of the same key, as one string. `uuid_tBusiness` picks the group and `uuid_tUserBusiness` the creator; `fJobReference`, `fCreatedTs` and `fPriority` are taken as sent too                                                                                                                                                                                                                                                                                             |

The job JSON's list keys, `assignees`, `followers`, `tags` and `todos`, work only from the stored form: a form field is one string, never a list (`model/feature_qrform.py:216-232`). A string there does not fail cleanly. `assignees` and `followers` run one lookup per character and add nobody, `tags` does nothing, and `todos`, or an `fPriorityNumber` field, ends the request with HTTP `500`; `todos` does so after the task is created.

**Response** `200`

```json
{
  "result": true,
  "message": "reported successfully",
  "serverTs": 1794387595000,
  "data": {
    "fJobReference": "48213907",
    "taskShareLink": "https://task.example.com/0d6e2c1a-4b7f-4e8a-9c3d-2f1b5a6e7d8c"
  }
}
```

* `fJobReference` is the request's value when one is sent. Otherwise it is the last six digits of the current time in milliseconds and two random digits.
* `taskShareLink` is set when the form turns on shareable links (`enable_shareable_link` on its success page), with or without `guest_email`: `https://task.snapfix.com/<token>` on the live server, a read-only link that lasts one year. Otherwise it is `null`.

**Errors:** all `200` with `result` `false`, except unexpected server errors. In the order the checks run:

* The abuse check's message with a reference code: the caller is blocked, for example after 50 submissions from one IP address in a minute ([Blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).
* "invalid authentication": the Basic login is missing or wrong. "invalid params": no form fields. "invalid authentication" again: `recaptcha_token` is missing or empty.
* "invalid recaptcha": Google doesn't mark the token as successful.
* "invalid code": unknown or deleted form. "code expired": its expiry has passed.
* "There is an issue with the data you have entered. Please try again and contact <support@snapfix.com> if the issue persists.": the form has created 50 tasks in the last minute.
* The parser's message: `jobchats` is not JSON. "Email is invalid": `guest_email` fails the pattern.
* "invalid business" or "invalid user business": the merged job JSON names no group, or no creator.
* "invalid job title"; "invalid job image" (see the table).
* "Issues generated using this QR code are normally stored in a Group within the Snapfix service. It seems like this Group may have been recently deleted. Please contact the front desk and let them know.": the group is unknown or deleted.
* "invalid user business": the named creator is missing or deleted, and the group has no admin.
* "invalid status" or "invalid sub status": the group has no "Red" status or no "New" sub-status.

**Side effects,** in order:

* [`qr_formdata_log`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata_log.md): one row with the job JSON and the whole request, including `guest_email` and `recaptcha_token`. It is written once every check has passed and linked to the task at the end (`model/feature_qrform.py:375-391`, `:965-966`); only linked rows count toward the per-form limit.
* [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md): a red task with the "New" sub-status in the named group. The creator is the user business named in `uuid_tUserBusiness` (the standard form names the "Snapbot QR" one), which may belong to any group, or the group's first admin when that one is missing or deleted (`:267-343`, `:452-490`).
* `log_ai_job`: one title row whenever `aiTitle` is present, even when empty; the standard and custom layouts always send it (`:494-514`).
* [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md): a "Created Task" item from the creator (type 6), then the job JSON's own chat items (the standard form has "This task was generated from a QR Code" from "Snapbot QR") and the request's `jobchats`, and a tracking-link item when a guest email is sent (`:516-541`, `:580-601`, `:934-963`).
* From the job JSON's lists: [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) and [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md) rows for listed users who belong to the group; [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md), [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md) and [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md) rows, creating tag folders and tags that don't exist yet; [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md) rows. Each item costs queries inside the request (`:603-931`).
* A [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md) entry for the task and for each of these rows while `WEB_QUEUE_SUPPORT` is on (`model/utils.py:302-304`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* With shareable links on: a [`url_job_token`](https://docs.snapfix.com/engineering-reference/db/tables/url_job_token.md) row, read-only for one year (`:544-576`). With `guest_email` as well: "Your Snapfix Task Link" through Amazon SES to that address, with the link and the task title in its HTML (`:137-141`, `:577-578`; `ses.py:14-54`).
* The photo: one public file in an image bucket whose name is a test bucket's in every mode \[[ASK-173](https://github.com/snapfix/docs/blob/main/ASK.md#ask-173-should-qr-photos-keep-going-to-the-bucket-named-testimagessnapfixio)]. It is uploaded before the group checks, so a refused submission can leave its photo behind.
* A push: one request to apipy's `/req-to-notify-user-for-qr-job`, which takes no login, for the group's admins, the members who may view all tasks, and the task's assignees and followers. Its title is the group's name and its text says that the creator created the task (`:968-1024`).
* In the background, when the request has a room, or has an image reference and the group has a site: a thread asks the Laravel guest suggestion routes for rooms, areas, tags and assignees, then adds a room, an area, the tags and the assignees through the `/v1/internal/tasks` routes as the Snapbot QR user. The submitted room replaces a suggested one. Without the guest token in authpy's settings it skips the suggestions, and without the internal login it skips the whole step (`:1026-1031`, `:1394-1468`). See [AI](https://docs.snapfix.com/engineering-reference/api/ai.md) and [Internal](https://docs.snapfix.com/engineering-reference/api/internal.md).

## GET /qr-form/{uuid}/rooms

Lists the rooms of the form's site, for the room picker on the form.

* **Auth:** the shared app Basic login; no user token (authpy @ 5d5758661c, `app.py:1460-1484`). The form must exist and not be deleted; its expiry is not checked.
* **Used by:** qr\_forms (`FormService.getFormRooms`, when a standard or custom form loads: qr\_forms @ bdfc4f20a5, `src/app/services/form/form.service.ts:51-56`). Which forms show the picker is in [QR form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md).

**Request**

| Name   | In   | Type   | Required | Rules         |
| ------ | ---- | ------ | -------- | ------------- |
| `uuid` | path | string | yes      | The form's ID |

**Response** `200`: `data` is a list of `{ "uuid", "roomName" }`: every live room of every live building in the site of the form's group, not only the group's rooms, in database order and with no paging (`model/feature_qrform.py:94-135`). An unknown or deleted form, or a deleted group, gives `[]` with `result` `true`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [
    { "uuid": "5f0c2a7e-9b1d-4c3a-8e2f-6d7a1b9c0e41", "roomName": "Room 101" },
    { "uuid": "a4e8d3b2-1f6c-4e9a-b7d5-2c8f0e6a3b19", "roomName": "Lobby" }
  ]
}
```

**Errors:** `200` with `result` `false`: "invalid authentication" (the Basic login is missing or wrong); the abuse check's message when the caller is blocked.

**Side effects:** no data change. The call and its answer are logged.

## QR form object

A group's QR form, as the Laravel list and create and php-apis `read_business_qr` return it. The two services use different field names for the same values.

| Laravel field                    | php-apis field                      | Type                            | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------- | ----------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                           | `uuid`                              | string                          | The form's ID. The link in the QR code ends with it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `url`                            | `url`                               | string                          | The public link. Laravel builds it from the server's `QR_DOMAIN` setting, a slash and `uuid` (api\_php\_live\_v2 @ ef3c4319f6, `config/app.php:89`, `app/Http/Controllers/v1/Versions/v1_0/App/QrFormController.php:42`, `:87`); php-apis uses `https://qr.snapfix.com/` on the live server. In production both give `https://qr.snapfix.com/<uuid>`: the web's "Group QR Codes" dialog showed that link for a form made through `GET /v1/app/businesses/{uuid}/qr` (round 1 live pass, [notes/crawl/groups.md](https://github.com/snapfix/docs/blob/main/notes/crawl/groups.md#qr-dialog)) |
| `posterTitle`                    | `poster_title`                      | string or null                  | The printed poster's title                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `posterDescription`              | `poster_description`                | string or null                  | The poster's text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `posterHackerWarning`            | `poster_hacker_warning`             | integer or null                 | `1` shows a warning on the poster, `0` hides it. New rows default to `1` ([`qr_formdata`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata.md))                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `posterHackerWarningDescription` | `poster_hacker_warning_description` | string or null                  | The warning's text. New rows default to "You will never be asked for a username or password". The staff API requires it when the flag is `1` (`app/Http/Requests/v1/Admin/QrForm/CreateQrFormRequest.php:24-25`)                                                                                                                                                                                                                                                                                                                                                                            |
| `inAppTitle`                     | `in_app_title`                      | string or null                  | The form's title in the apps. The web shows it, or `posterTitle` when it is an empty string (web\_app\_v2 @ 0989b8e685, `src/app/pages/group-settings/group-settings-group-qr/group-settings-group-qr.component.ts:83-87`)                                                                                                                                                                                                                                                                                                                                                                  |
| `formEnum`                       | `form_enum`                         | string                          | The type: `basic_v2` (the standard form), `dropdown_v1`, `radiobutton_v1` or `dynamic_v1` (`app/Enums/QrFromType.php:7-10`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `createdTs`, `modifiedTs`        | `fCreatedTs`, `fModifiedTs`         | string or null; integer or null | When the form was created and last changed. Laravel returns ISO 8601 strings in UTC, such as `2026-11-14T09:00:00.000000Z`, because its resource passes the model's date objects through (`app/Http/Resources/v1/BusinessQrResource.php:27-28`, `app/Traits/ModelUpdate.php:50-57`); php-apis returns milliseconds. The web's model types them as numbers (`src/app/models/group/group.model.ts:171-180`), but no client reads them                                                                                                                                                         |

Neither list returns the form's expiry or its visibility flag.

## Form details object

What [GET /qr-form/{uuid}](#get-qr-formuuid) returns, from the form's row and its site (authpy @ 5d5758661c, `model/feature_qrform.py:42-92`).

| Field                 | Type    | Meaning                                                                                                                                                                                                                               |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                | string  | The form's type (`form_enum`)                                                                                                                                                                                                         |
| `form_schema`         | object  | The layout: `page_form` (the title, the inputs and the submit button), `page_success` and `page_fail`. It is the row's `dynamic_form_json` ([`qr_formdata`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata.md)) |
| `parent_uuid`         | string  | The site of the form's group                                                                                                                                                                                                          |
| `aiSuggestionEnabled` | integer | The site's AI suggestion switch (`tPri_SettingsParent.fAiSuggestionEnabled`); `0` when the site has no live settings row                                                                                                              |

The group's ID is not returned.


---

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