> 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/how-the-apps-work/screens/staff/surveys.md).

# Survey

{% 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)). Platforms: web. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/staff/surveys.md).
{% endhint %}

Staff create, edit, import, download and delete the pre-registration surveys that the apps show before sign-up, each with its dates, countries, devices and questions.

* **Where:** admin app `/survey`; menu "Survey".
* **Who:** the menu item shows only to usernames on the app's built-in `adminUsers` list (webadmin\_angular @ db972390b8, `src/app/app.component.ts:246-258`, `src/app/shared/config.ts:21-28`), but the route checks only that a session exists, so any signed-in user can open the page by its address. The survey routes check the staff flag on the server ([Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsurvey)): a token without it gets `400`, no token `401`.
* **Feature:** [Survey setup](https://docs.snapfix.com/product/features/staff/survey-setup.md)

## Layout

1. The title "Survey", then a round "+" button with the text "Create a new Survey", disabled while the list loads or a delete runs.
2. The surveys table, 10 rows per page by default (10, 20, 50 or 100) with a page jump. Columns:
   * "Title", with a search, and "Description", both from the survey's form.
   * "Active": "Yes" or "No".
   * "Android", "Ios" and "Web": "Yes" when the survey shows on that device; a survey with no device list shows "Yes" in all three. The iOS label is "Ios" here and "IOS" on [Marketing popups](https://docs.snapfix.com/how-the-apps-work/screens/staff/marketing-popups.md).
   * "Start Date" and "End Date", as YYYY-MM-DD in the browser's time zone.
   * "Action", fixed at the right: edit, "Download Survey JSON" and "Delete".
   * "Title", "Active", "Start Date" and "End Date" sort in the browser.

## Inputs

| Field        | Type                                | Required | Default | Rules and messages                                                                                                                                                                                                                                                                            |
| ------------ | ----------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Title search | Text, from the column's search icon | No       | Empty   | "Search" and "Reset" as on [SMS/E-mail delivery](https://docs.snapfix.com/how-the-apps-work/screens/staff/sms-email-delivery.md#inputs); the box's placeholder reads "Search name". Keeps the loaded surveys whose title contains the text, ignoring case, once "Search" or Enter is pressed. |

## Actions

| Action                      | Who                | What happens                                                                                                                                                                                 | API                                                                                                                      |
| --------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Open the page               | Any signed-in user | Loads every survey, active and inactive, with no paging.                                                                                                                                     | [`GET /v1/admin/survey`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsurvey)                  |
| "+" ("Create a new Survey") | Same               | Opens [Create Survey](#create-survey-and-edit-survey).                                                                                                                                       | None                                                                                                                     |
| Edit                        | Same               | Opens [Edit Survey](#create-survey-and-edit-survey) with the survey. Disabled while a delete runs.                                                                                           | None                                                                                                                     |
| "Download Survey JSON"      | Same               | Downloads the survey's form as `survey-<creation time in ms>.json`. The file is cut short at the first "#".                                                                                  | None                                                                                                                     |
| "Delete"                    | Same               | Asks "Delete Survey" / "Are you sure you want to delete the survey?" with a danger "Delete" and "Cancel". On success "Success" shows and the row goes; a refusal shows the server's message. | [`DELETE /v1/admin/survey/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#delete-v1adminsurveyuuid) |

## States

* **Loading:** the table shows its loading state.
* **Empty:** the table's empty placeholder.
* **Error:** the list shows no error message, and a failed list leaves the table empty.
* **No permission:** none in the app: the menu item is hidden from staff off the list, but the route is open.

## Dialogs and sheets

### Create Survey and Edit Survey

"Create Survey" or "Edit Survey", 1500 px wide, with the tabs "Details" and "Components"; each tab's title is marked while that tab is incomplete. Footer: "Import" at the left, "Cancel" and "Save".

**Details tab**

| Field              | Type              | Required | Default                      | Rules and messages                                                                                                                 |
| ------------------ | ----------------- | -------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Title              | Text              | No       | Empty                        | Up to 35 characters, with a counter.                                                                                               |
| Submit Button Text | Text              | Yes      | "Submit"                     | Up to 10 characters, with a counter. "Submit Button Text is required."                                                             |
| Date Range         | Date range picker | Yes      | Empty for a new survey       | "Date Rrange is required.". Saved from 00:00:00 GMT on the first day to 23:59:59 GMT on the last. See [Date checks](#date-checks). |
| Countries          | Multi-select      | No       | Empty, meaning every country | The countries list, by name; up to three show as tags.                                                                             |
| Description        | Text area         | No       | Empty                        | Up to 200 characters, with a counter.                                                                                              |
| Active             | Switch            | No       | On                           | Shown only when editing; a new survey is saved active.                                                                             |
| Android, Ios, Web  | Switches          | No       | All on                       | At least one stays on: the switch that would turn off the last one is disabled.                                                    |

**Components tab.** A type select ("Checkboxes", "Dropdown", "Radiobuttons" or "Multiline", "Checkboxes" at first) and a "+" button (hover text "Add component") with "Add Component" add a component at the end. Components are dragged by their handle to reorder, and deleted with their own button.

| Field                                                    | Type                                 | Required     | Default            | Rules and messages                                                                                                                           |
| -------------------------------------------------------- | ------------------------------------ | ------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| ID                                                       | Text, read-only                      |              | The component type |                                                                                                                                              |
| Label ("Component Label")                                | Text                                 | No           | Empty              | Up to 35 characters.                                                                                                                         |
| Subtitle ("Component Subtitle"), Hint ("Component Hint") | Text                                 | No           | Empty              | Up to 50 characters each.                                                                                                                    |
| Mandatory                                                | Checkbox                             | No           | Off                |                                                                                                                                              |
| Content Random                                           | Checkbox                             | No           | Off                | Not on "Multiline".                                                                                                                          |
| Content items                                            | List, in a panel "Content items (N)" | At least one | One empty item     | Not on "Multiline". "Add content item" adds one; items are dragged to reorder; an item's delete button is disabled while it is the only one. |
| Item Text ("Component Item Text")                        | Text                                 | Yes          | Empty              | Up to 100 characters, with a counter. "Text is required."                                                                                    |
| Item Hint ("Component Item Hint")                        | Text                                 | No           | Empty              | Up to 50 characters.                                                                                                                         |
| Item Default, Force To Bottom                            | Checkboxes                           | No           | Off                | One item at a time each: ticking one clears it on the others.                                                                                |
| Item Multiline                                           | Checkbox                             | No           | Off                |                                                                                                                                              |
| Item Multiline Hint ("Component Item Multiline Hint")    | Text                                 | No           | Empty              | Up to 50 characters; shown on every item, whatever "Multiline" says.                                                                         |

| Action   | Who                | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | API                                                                                                                                                                                                                                        |
| -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| "Save"   | Any signed-in user | Disabled until the details are valid, the dates pass the check below, and there is at least one valid component; a component without content items, or with an empty item text, is invalid. Sends the dates, devices, countries (keeping a stored survey's city, continent and region filters), the active flag and the form: title, submit button text, description and components. On success "Success" shows, the dialog closes, and the row is added at the end or updated. A refusal shows the server's message and the dialog stays open. While saving, "Save" shows a spinner and "Import", "Cancel", the close button and a click outside do nothing. | [`POST /v1/admin/survey`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsurvey) (new), [`PUT /v1/admin/survey/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminsurveyuuid) (edit) |
| "Import" | Same               | Opens [Import Survey JSON schema](#import-survey-json-schema).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | None                                                                                                                                                                                                                                       |
| "Cancel" | Same               | Closes without saving.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | None                                                                                                                                                                                                                                       |

Imported components whose type is not one of the four are not shown and are saved as empty components.

#### Date checks

The app checks the range against the other active surveys on the page: those not marked inactive, the edited one left out. The check runs when the dates, the countries or the Active switch change; an edited survey opens as valid.

* A survey clashes when the ranges overlap, or one starts on the day the other ends, and the two share a country, or neither has one. A survey for some countries does not clash with one for every country; the server allows that pair too and serves the country survey 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)].
* When the survey being saved is active and clashes, the warning "Active Survey Detected" opens. It lists the other survey's "Title:", "Start Date:", "End Date:" and, when it has countries, "Country:" or "Countries:" with the shared ones marked, then "If you wish to apply the selected date range and countries, please change the date range or the countries, or set the detected survey to inactive." Without countries it ends "If you wish to apply the selected date range, please specify a country or set the detected survey to inactive." The text is built as HTML from the other survey's title. "Save" stays disabled until the clash is gone.
* The check compares the picked dates at local midnight with stored GMT days, so it can be a day off.
* The server runs the same rule even for an inactive survey and answers `422` with its message ([`POST /v1/admin/survey`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsurvey)) \[[ASK-207](https://github.com/snapfix/docs/blob/main/ASK.md#ask-207-which-surveys-should-the-date-overlap-check-compare)].

### Import Survey JSON schema

"Import Survey JSON schema", 700 px wide, with the tabs "JSON File" and "JSON Editor".

* **JSON File:** a drop area, "Upload JSON file", for a `.json` file. A file whose type is not JSON gets "Please upload correct json file!", and an empty one "Unable to read imported file data.". A file that is read opens in the editor tab; a file that is not valid JSON gives no message and leaves the editor empty.
* **JSON Editor:** a code editor that checks the text against the survey schema, which requires a `page_form` object.

| Action   | Who                | What happens                                                                                                                                                                                                                                                                                                   | API  |
| -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| "Import" | Any signed-in user | Enabled only when the JSON passes the schema. Fills the title, description and submit button text, and replaces the components when the file has some; texts longer than a field's limit are cut. The dates, countries, devices and the Active switch do not change. A `page_success` part is dropped on save. | None |
| "Cancel" | Same               | Closes.                                                                                                                                                                                                                                                                                                        | None |


---

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

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

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

```
GET https://docs.snapfix.com/how-the-apps-work/screens/staff/surveys.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.
