> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/qr/qr-forms.md).

# QR forms

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/qr-forms.md).
{% endhint %}

**QR forms** let anyone report a problem or make a request by scanning a **group**'s **QR code**, without the app and without an account. The code opens a public form at `https://qr.snapfix.com/<form ID>`, which can ask for a photo, where the problem is, notes, a **room** or a choice from a list. Submitting creates a **task** in the group and shows its reference, and the confirmation page can show a tracking link. Each group has one standard code, which a group admin makes in **Group QR codes**, on the web or in the apps, and downloads as an image or a PDF. Snapfix staff build custom forms in the staff admin app. It lets guests, tenants and staff without an account report to a team.

## Rules

### Codes

* A group has one standard form (`basic_v2`, "Standard"). A group admin makes it with "Generate QR", and a second one is refused with "Default QR for this group already exists!". Other members get the server's message ([`POST /v1/app/businesses/{businessUuid}/qr`](https://docs.snapfix.com/engineering-reference/api/qr.md#post-v1appbusinessesbusinessuuidqr)).
* No screen removes or replaces a group's code, so a printed code keeps working as long as its form exists \[[ASK-74](https://github.com/snapfix/docs/blob/main/ASK.md#ask-74-can-a-groups-qr-code-be-removed-or-replaced)]. Staff can change or delete forms through the staff routes ([Related routes](https://docs.snapfix.com/engineering-reference/api/qr.md#related-routes)).
* A deleted standard form still blocks a new one, and while any form anywhere had an expiry, "Generate QR" would fail for every group.
* The code's link is `https://qr.snapfix.com/<form ID>` on the web and in the apps ([QR form object](https://docs.snapfix.com/engineering-reference/api/qr.md#qr-form-object)).
* On the web, anyone who can open the group's task list sees the QR button there, and people with settings access see it in the group's settings. The apps show the settings button to admins only, and the iOS task "+" menu item to everyone \[[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)] ([Group QR codes](https://docs.snapfix.com/how-the-apps-work/screens/groups/qr-codes.md)). The web's list itself lets in any member who is not read-only.
* The web's list also shows deleted forms, whose codes no longer open, and the two lists treat expiry differently.
* The web and iOS download a code as JPG or PDF, and Android saves the image to the gallery or makes a PDF. The web copies the link, iOS shares the image or the link, and Android has neither ([Group QR codes](https://docs.snapfix.com/how-the-apps-work/screens/groups/qr-codes.md#actions)). The PDF's steps are in English only.

### Forms

* The form's type decides its page: the standard form, a custom form, a choice form (`radiobutton_v1`) or a dropdown form (`dropdown_v1`). Any other type shows as a custom form ([Form types](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#form-types)).
* Staff build custom forms in the admin app, with their title, poster, fields and success and failure pages. The older types can't be edited there, and the screen makes no choice or dropdown forms, though the staff API accepts them ([QR management](https://docs.snapfix.com/how-the-apps-work/screens/staff/qr-management.md), [Form types](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#form-types)).
* The standard form asks for a photo (optional), "2. Where is it? \*" (required, the task's title), notes (optional, the task's description) and a room (shown when the site has rooms) ([Standard form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#standard-form)). The required field shows no message, holds the AI's title, and accepts a title of only spaces.
* A custom form shows the fields its layout lists. A layout with two photo, title or description fields, or an input other than text or email, gets "This QR form is not currently active" ([Custom form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#custom-form)).
* A custom form shows the room picker only for sites on a list kept in Firebase, outside the repos. Where the picker is hidden, a room the AI suggests is still sent \[[ASK-175](https://github.com/snapfix/docs/blob/main/ASK.md#ask-175-should-custom-qr-forms-show-the-room-picker-for-every-site-with-rooms-and-send-an-ai-room-when-the-picker-is-hidden)] ([Custom form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#custom-form)).
* The room list holds every live room of the site of the form's group, not only the group's rooms, and the page loads it even when the picker is hidden ([`GET /qr-form/{uuid}/rooms`](https://docs.snapfix.com/engineering-reference/api/qr.md#get-qr-formuuidrooms)).
* The dropdown form needs its notes, although its built-in label calls them optional.
* A photo from the camera or the gallery is resized to fit 800 by 800 pixels, and the guest can draw on it ([Photo](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#photo)).

### AI suggestions on the form

* The live form page runs a newer build (version 1.0.9) than the code the docs are pinned to, and it differs in three ways \[[ASK-226](https://github.com/snapfix/docs/blob/main/ASK.md#ask-226-should-master-and-syncyml-follow-the-branch-that-runs-on-qrsnapfixcom)]:
  * On the standard and custom forms of a site with AI suggestions on, any photo, taken or chosen, gets a suggested title and room. The title fills an empty title field and the room is picked when it is in the list, each with an AI mark ([Photo](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#photo)).
  * Removing the photo also clears an AI title the guest has not edited and an AI room the guest has not changed.
  * The form tells the server whether the room sent is the one the AI suggested (`aiRoomSuggestion`).
* The choice and dropdown forms get no suggestions.
* After a submit with a room, or with a photo the AI has read, the server also asks the AI for the task's room, area, tags and assignees and adds them; a room the guest picked wins \[[ASK-186](https://github.com/snapfix/docs/blob/main/ASK.md#ask-186-should-the-ai-add-assignees-tags-rooms-and-areas-to-qr-form-tasks)] ([`POST /qr-form/{uuid}`](https://docs.snapfix.com/engineering-reference/api/qr.md#post-qr-formuuid)). Those background calls share one rate limit across every customer, and past it the task just gets no suggestions. See [Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md).

### Submitting

* Anyone with the code or its link can open and submit the form. The page signs no one in; it carries a shared login built into its code ([QR form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md)).
* "Submit" asks the browser for the location, gets a reCAPTCHA token and sends the form. The location prompt has no explanation and no time limit; without a location, 0,0 is stored. The server refuses a submit without a token, and its token check is weak ([Location and reCAPTCHA](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#location-and-recaptcha)).
* A submit creates a red task with the "New" sub-status in the group that the form's stored job names, made by the creator it names ("Snapbot QR" for the standard form). The page sends no group, but a hand-made request can name another group and creator ([`POST /qr-form/{uuid}`](https://docs.snapfix.com/engineering-reference/api/qr.md#post-qr-formuuid)).
* A submit needs a title, from the form or its stored job, and a photo or a text that stands in for it: "invalid job title" or "invalid job image". A custom form whose optional title is left empty is refused, even with a photo. A choice form sends only the picked option, so it works only when its stored job has a title; the live choice forms in the staging copy all have one ([Choice form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#choice-form)).
* The task gets a "Created Task" chat item, the stored job's own chat items and the chat messages the form sent ([What a submit creates](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#what-a-submit-creates)).
* The group's admins, the members who may view all tasks, and the task's assignees and followers get a push ([Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md#which-events-push)).
* Limits: 50 submits a minute per IP address and 50 tasks a minute per form. The address comes from a header a client may be able to set, and the two reads have no limit ([`POST /qr-form/{uuid}`](https://docs.snapfix.com/engineering-reference/api/qr.md#post-qr-formuuid)).
* The success page shows "Ref:" with the task's reference. A custom form whose success page turns on share links also shows a read-only tracking link that lasts a year, with "Click the link to track progress of this task.", and emails it when the guest typed an address. The staff tool turns this on for every new custom form \[[ASK-174](https://github.com/snapfix/docs/blob/main/ASK.md#ask-174-should-new-custom-qr-forms-send-a-tracking-link-by-default)]; the standard form has no such switch ([After a submit](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#after-a-submit), [Shared task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/shared-task.md#where-links-come-from)).
* The photo is stored public-read under the type the browser sends, in an image bucket named as a test bucket \[[ASK-173](https://github.com/snapfix/docs/blob/main/ASK.md#ask-173-should-qr-photos-keep-going-to-the-bucket-named-testimagessnapfixio)].
* The typed text, the guest's email and the location go to Firebase Analytics, and authpy's logs keep the whole request.

### Limits and plans

* No plan limit applies to QR forms in the code. The only caps are the submit limits above.

## Flow

```mermaid
flowchart TD
  gen["Group admin: Generate QR"] --> code["Standard code and link"]
  staff["Staff: custom form in the admin app"] --> code
  code --> scan["Guest scans the code or opens the link"]
  scan --> load{"Form found, live and readable?"}
  load -- "wrong, deleted or expired" --> bad["This QR appears to be incorrect"]
  load -- "layout the page can't show" --> inactive["This QR form is not currently active"]
  load -- yes --> fill["Guest fills in the form"]
  fill -- "photo, AI on" --> sugg["Title and room suggested"]
  sugg --> submit
  fill --> submit["Submit: location and reCAPTCHA token"]
  submit -- refused --> fail["Alert, then the failure page"]
  submit -- "no answer" --> failpage["Failure page"]
  submit -- accepted --> task["Red task in the group"]
  task --> notify["Admins, viewers, assignees and followers notified"]
  task --> confirm["Success page: reference, and a tracking link if on"]
  task -. "room or AI-read photo" .-> bg["Room, area, tags and assignees added in the background"]
```

## Platforms

| Capability                    | Web                                                                                                                                                                                                | iOS                                          | Android                                  |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------- |
| Open and submit the form      | Yes, at the code's link                                                                                                                                                                            | No; the code opens the web form              | No; the code opens the web form          |
| See a group's codes           | From the task list and the group's settings                                                                                                                                                        | From settings (admins) and the task "+" menu | From settings (admins) and the task menu |
| Generate the standard code    | Group admins                                                                                                                                                                                       | Group admins                                 | Group admins                             |
| Download a code               | JPG and PDF                                                                                                                                                                                        | JPG and PDF, with a share sheet              | "Save to Gallery" and PDF                |
| Copy or share the link        | Copy                                                                                                                                                                                               | Share the image or the link                  | No                                       |
| AI title and room on the form | Yes, after any photo, on sites with AI suggestions on \[[ASK-226](https://github.com/snapfix/docs/blob/main/ASK.md#ask-226-should-master-and-syncyml-follow-the-branch-that-runs-on-qrsnapfixcom)] | No                                           | No                                       |
| Build forms                   | Staff, in the admin app                                                                                                                                                                            | No                                           | No                                       |

## Screens

* [QR form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md): the public form, its success and failure pages, and its error pages.
* [Group QR codes](https://docs.snapfix.com/how-the-apps-work/screens/groups/qr-codes.md): a group's codes, their downloads and "Generate QR", on the web, iOS and Android.
* [Shared task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/shared-task.md): the read-only page a tracking link opens.
* [QR management (admin app)](https://docs.snapfix.com/how-the-apps-work/screens/staff/qr-management.md): where staff build, edit, copy and delete forms.

## API and data

* [`GET /v1/app/businesses/{businessUuid}/qr`](https://docs.snapfix.com/engineering-reference/api/qr.md#get-v1appbusinessesbusinessuuidqr): a group's codes, for the web. [`POST ?action=read_business_qr`](https://docs.snapfix.com/engineering-reference/api/qr.md#post-actionread_business_qr): the same for iOS and Android.
* [`POST /v1/app/businesses/{businessUuid}/qr`](https://docs.snapfix.com/engineering-reference/api/qr.md#post-v1appbusinessesbusinessuuidqr): "Generate QR", on all three.
* [`GET /qr-form/{uuid}`](https://docs.snapfix.com/engineering-reference/api/qr.md#get-qr-formuuid), [`GET /qr-form/{uuid}/rooms`](https://docs.snapfix.com/engineering-reference/api/qr.md#get-qr-formuuidrooms) and [`POST /qr-form/{uuid}`](https://docs.snapfix.com/engineering-reference/api/qr.md#post-qr-formuuid): the public form's details, rooms and submit. Hand-made requests with some extra fields fail part way, and one request can cost unbounded work.
* The form's suggestions: [`POST /v1/guest/suggestions/title`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1guestsuggestionstitle) and [`POST /v1/guest/suggestions/rooms`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1guestsuggestionsrooms).
* The push: [`POST /req-to-notify-user-for-qr-job`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user-for-qr-job), which needs no login.
* The staff routes under `/v1/admin/qr-form` are in [Related routes](https://docs.snapfix.com/engineering-reference/api/qr.md#related-routes). The old php-apis actions `generate_business_qr` and `qr_task` have no caller; `qr_task` still creates tasks, and service users, with no user login.
* Tables: [`qr_formdata`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata.md) (the forms), [`qr_formdata_log`](https://docs.snapfix.com/engineering-reference/db/tables/qr_formdata_log.md) (each accepted submit), [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) and [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) (the task and its chat), [`url_job_token`](https://docs.snapfix.com/engineering-reference/db/tables/url_job_token.md) (tracking links) and [`tPri_Log_API_IP_RateLimit`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_api_ip_ratelimit.md) (the per-IP count).

## Depends on

* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the group that gets the task, its "Red" status and "New" sub-status, and the people notified.
* [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md) and [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): a submit creates an ordinary task.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): the push after each submit.
* [Sharing tasks](https://docs.snapfix.com/product/features/tasks/task-sharing.md): the tracking link.
* [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md): the rooms on the form.
* [Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md) and [Site details](https://docs.snapfix.com/product/features/console/site-details.md): the AI suggestions and the site's switch for them.
* [Staff admin app](https://docs.snapfix.com/product/features/staff/staff-admin.md): where staff build forms.
* Google reCAPTCHA, Firebase Remote Config (the room-picker list) and Firebase Analytics (the form's events).

## Edge cases

* **Wrong, deleted or expired code:** "This QR appears to be incorrect". An expired form shows that text too, though no code sets an expiry yet ([Error pages](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#error-pages)).
* **Deleted group:** the form still opens, and the submit is refused with a message to tell the front desk ([`POST /qr-form/{uuid}`](https://docs.snapfix.com/engineering-reference/api/qr.md#post-qr-formuuid)).
* **Group without a "Red" status or "New" sub-status:** the submit is refused with "invalid status" or "invalid sub status".
* **Failed submit:** the guest sees the server's text, which can be developer wording such as "invalid authentication", and "Try again" brings back an empty form.
* **Second press while the photo is prepared:** the standard and dropdown forms can send twice, or wait for ever.
* **Camera refused:** the gallery button still works ([Photo](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md#photo)).
* **Offline:** a submit ends on the failure page, with no alert.
* **Room of another site:** only a room of the group's site is added to the task.
* **Tracking page:** it returns more data than it shows ([Shared task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/shared-task.md)).
* **Time zones and integrations:** none beyond the Google and Firebase services above.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/qr/qr-forms.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.
