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

# Survey setup

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

Snapfix staff build the **pre-registration surveys** in the [staff admin app](https://docs.snapfix.com/product/features/staff/staff-admin.md): short sets of questions shown to a person on the app's sign-in screen, before they sign in. A survey has a title, a submit button text, a **date range**, the **countries** and **devices** it is for, and its **components** (the questions). The server gives each request at most one survey and logs each request and answer. Staff can also download a survey as JSON and import one from JSON. Today only the Android app shows the survey. These are not the NPS and product feedback surveys: see [Feedback surveys](https://docs.snapfix.com/product/features/notifications/feedback-surveys.md).

## Rules

### Who can set them up

* The "Survey" menu item shows only to usernames on the app's built-in list, but the page itself has no check, so any staff session can open it by its address. The survey routes check the staff flag on the server ([Survey](https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.md), [`GET /v1/admin/survey`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsurvey)).

### Setting up a survey

* The details are a title of up to 35 characters, a required submit button text of up to 10 (default "Submit"), a required date range, the countries (none means every country), a description of up to 200 characters, and switches for Android, iOS and the web, of which at least one stays on ([Survey](https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.md#create-survey-and-edit-survey)).
* A new survey is saved active; the "Active" switch shows only when a survey is edited.
* A survey needs at least one component, of type "Checkboxes", "Dropdown", "Radiobuttons" or "Multiline", each with a label, a subtitle, a hint and a mandatory flag. Every type but "Multiline" needs at least one content item with a text of up to 100 characters; one item at most can be the default and one can be forced to the bottom ([Survey](https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.md#create-survey-and-edit-survey)).
* The list shows a survey with no device list as on for all three devices ([Survey](https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.md#layout)).
* A missing start or end date makes the server answer with an error instead of a message.

### Dates and overlaps

* A survey runs from 00:00:00 GMT on its first day to 23:59:59 GMT on its last. The list, the dialog and the overlap check use the browser's time zone, so outside GMT a date can show, or be checked, one day off, and saving an edited survey can move a date.
* Two active surveys may not overlap, or touch on one day, when they share a country or neither has one. A survey for some countries may overlap one for every country, and the country survey is served first. Device types are not compared \[[ASK-207](https://github.com/snapfix/docs/blob/main/ASK.md#ask-207-which-surveys-should-the-date-overlap-check-compare)] ([Date checks](https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.md#date-checks)).
* The admin app checks only while the survey being saved is active, and blocks "Save" with the "Active Survey Detected" warning, which names the other survey. The server applies the rule to every save, inactive surveys too, and answers `422` \[[ASK-207](https://github.com/snapfix/docs/blob/main/ASK.md#ask-207-which-surveys-should-the-date-overlap-check-compare)].

### Import and download

* "Import" takes a JSON file or the JSON editor; the JSON needs a `page_form` object. It fills the title, description, submit button text and components; the dates, countries, devices and the Active switch stay as they were ([Import Survey JSON schema](https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.md#import-survey-json-schema)).
* A file that is not valid JSON gives no message. An imported component of an unknown type is saved as an empty component, and a `page_success` part is dropped on save.
* "Download Survey JSON" saves the survey's form as `survey-<creation time in ms>.json`, cut short at the first "#".
* "Delete" asks first, then marks the survey deleted; it leaves the list and is no longer served ([`DELETE /v1/admin/survey/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#delete-v1adminsurveyuuid)).

### Which survey a person sees

* The app asks for one survey. The server returns the newest survey that is active, inside its dates and matches the caller's country and device; a survey that names countries comes before one for every country. When nothing matches, the answer holds no survey ([`GET /v1/guest/survey/prereg`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-v1guestsurveyprereg); api\_php\_live\_v2 @ ef3c4319f6, `app/Services/PreRegSurveyService.php:70-101`).
* The country comes from the caller's IP address; when it is unknown, only surveys for every country match. The device comes from the request's device type header; a survey with no devices matches every device, and a request without the header is not filtered by device (`PreRegSurveyService.php:77-97`, `app/Http/Controllers/v1/Versions/v1_0/Guest/PreRegSurveyController.php:24`).
* Only Android asks: its sign-in screen requests a survey each time it opens until the phone's survey flag is on. A submit turns the flag on, and so do a successful sign-in, a registration, a password reset and a deep link. iOS never opens the screen that asks, and no web page that asks can be reached, so the iOS and web switches have no effect today ([Pre-registration survey](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/pre-registration-survey.md)).
* Each request writes a log row with the caller's IP address and location, also when no survey applies, and no job deletes those rows. Each answer and each dismissal is logged too; a field in the answers can overwrite the stored metadata.
* The survey routes are guest routes: they take the shared guest login and the per-IP limits of the guest group.

## Flow

```mermaid
flowchart TD
  create["Staff creates, edits or imports a survey"] --> active{"Survey active?"}
  active -- "yes" --> overlap{"Overlaps an active survey for a shared country, or both for every country?"}
  overlap -- "yes" --> blocked["Active Survey Detected: Save stays off"]
  overlap -- "no" --> saved["Saved, dates as GMT days"]
  active -- "no" --> saved
  saved --> android["Android sign-in screen opens, survey flag off"]
  android --> match{"Active, in its dates, matching country and device?"}
  match -- "no" --> none["No survey"]
  match -- "yes" --> shown["One survey: country surveys first, then the newest"]
  shown --> answer["Submit or dismiss: logged"]
```

## Platforms

| Capability                                        | Web                                  | iOS                            | Android                                                        |
| ------------------------------------------------- | ------------------------------------ | ------------------------------ | -------------------------------------------------------------- |
| Create, edit, import, download and delete surveys | Yes, in the admin app                | No                             | No                                                             |
| Show the survey to a person                       | No: no page that asks can be reached | No: the screen is never opened | Yes, on the sign-in screen until the phone's survey flag is on |
| Send answers and dismissals                       | No                                   | No                             | Yes                                                            |

## Screens

* [Survey](https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.md): the list, the create and edit dialog, the import and the JSON download.
* [Pre-registration survey](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/pre-registration-survey.md): the survey as the app shows it.

## API and data

* Staff: [`GET /v1/admin/survey`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsurvey), [`POST /v1/admin/survey`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsurvey), [`PUT /v1/admin/survey/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminsurveyuuid) and [`DELETE /v1/admin/survey/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#delete-v1adminsurveyuuid) ([Survey object](https://docs.snapfix.com/engineering-reference/api/staff.md#survey-object)); the countries come from the [Reference API](https://docs.snapfix.com/engineering-reference/api/reference.md).
* Apps: [`GET /v1/guest/survey/prereg`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#get-v1guestsurveyprereg) serves the survey and logs the request; [`POST /v1/guest/survey/prereg`](https://docs.snapfix.com/engineering-reference/api/onboarding.md#post-v1guestsurveyprereg) takes the answers or a dismissal.
* Tables: [`tPri_PreRegSurvey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_preregsurvey.md) (the surveys), [`tPri_Log_PreRegSurvey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_preregsurvey.md) (requests, answers and dismissals) and [`tPri_Log_PreRegSurveyMetadata`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_preregsurveymetadata.md).

## Depends on

* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md): the Android sign-in screen, where the survey shows.
* [Feedback surveys](https://docs.snapfix.com/product/features/notifications/feedback-surveys.md): a separate survey system.
* [Staff admin app](https://docs.snapfix.com/product/features/staff/staff-admin.md): the sign-in, and the menu item that the built-in list controls.

## Edge cases

* **No survey matches, or the survey is expired, inactive or deleted:** nothing is shown.
* **Country unknown:** only surveys for every country match.
* **Device header missing:** the device is not checked, so a survey meant for one device can show.
* **Time zones:** survey days are GMT days; outside GMT the admin app shows and checks them a day off.
* **Failed send on Android:** an alert shows the server's message and the answers are lost ([Pre-registration survey](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/pre-registration-survey.md#states)).
* **Failed list in the admin app:** no message; the table stays empty.
* **Offline:** not applicable to the admin app. On Android, a send without a connection shows "No Connection" and sends nothing ([Pre-registration survey](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/pre-registration-survey.md#states)).


---

# 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/staff/survey-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
