> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insito.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating surveys

> Build a survey in the Insito dashboard — name, trigger key, questions, throttling, and activation.

The survey builder lives at
[admin.insito.app](https://admin.insito.app) → your project →
**Surveys** → **New survey**. This page walks through each step.

## The builder

A survey has six tabs:

1. **Questions** — at least one answerable question; up to 20 items total
   (including optional welcome and end screens).
2. **Logic** — branching rules between questions.
3. **Trigger** — trigger conditions (event keys, screen visits, app open),
   throttling, and when to show the modal.
4. **Audience** — device and user-property filters.
5. **Schedule** — start/end dates, timezone, and response caps.
6. **Responses** — the survey's collected responses (table with CSV export).

While editing, changes **autosave to a draft** (debounced, on tab switch, and
when you leave a field). Live respondents keep seeing the last **published**
version until you explicitly publish.

## 1. Naming and status

<ParamField path="Survey name" required>
  Edit it in the builder header. It's an internal label shown across the
  dashboard (survey list, analytics), **not** inside the in-app modal. Use
  something descriptive (`Post-checkout NPS Q2 2026`) so it's easy to find.
</ParamField>

<ParamField path="Trigger key">
  The `trigger_key` uniquely identifies the survey per project and is derived
  from the survey's primary **App event** key on the Trigger tab (or slugified
  from the name). Event keys allow the characters `A–Z a–z 0–9 _` (up to 128,
  case-sensitive). See [Triggers](/concepts/triggers).
</ParamField>

<ParamField path="Status" default="draft">
  `draft` = never shown to users. `active` = eligible. `paused` =
  temporarily hidden. `scheduled` = activates at the configured start
  time. Toggling active/paused from the survey list takes effect within
  seconds — no app rebuild needed.
</ParamField>

Open **Survey settings** (gear icon) for description and
[behavior toggles](/dashboard/survey-settings) like branding, question
numbers, back navigation, and autosave.

## 2. Throttling

On the **Trigger** tab, set **Minimum days between shows** (`throttle_days`,
default **7**, range 0–365). Set it to `0` to disable throttling for the survey.

<Tip>
  Throttling is **per project, per user** — once any survey in the project is
  shown to a user, they won't be shown another until the window elapses. See
  [Throttling](/concepts/throttling) for the full mechanism and per-survey show
  caps.
</Tip>

## 3. Questions

Add at least one answerable question. A survey holds up to **20 questions
total**, including optional welcome and end screens. Respondents see them
one at a time inside the modal. When **Allow back button** is enabled in
survey settings, respondents can revisit earlier questions; optional
questions still show **Skip**.

### Question types

<CardGroup cols={2}>
  <Card title="NPS (0–10)" icon="chart-simple">
    The standard NPS scale. Detractors (0–6), passives (7–8),
    promoters (9–10). Insito auto-scores responses and computes the
    canonical NPS in the analytics view.
  </Card>

  <Card title="Rating (1–5)" icon="star">
    Five-point star rating. Best for "how easy was that?" or feature
    satisfaction.
  </Card>

  <Card title="Multiple choice" icon="list-check">
    Single-select by default, multi-select toggleable. Each option
    is a free-form string up to 120 characters.
  </Card>

  <Card title="Open text" icon="comment">
    Free text input with a configurable max length (default 500
    chars). Lands verbatim in the responses tab.
  </Card>
</CardGroup>

### Common patterns

**Pure NPS** (one question, two if you want a follow-up):

1. NPS: "How likely are you to recommend us to a friend?"
2. Open text: "What's the main reason for your score?"

**Feature satisfaction** (three questions):

1. Rating: "How satisfied are you with this feature?"
2. Multiple choice: "What did you like most?" — `["Speed", "Reliability", "Design", "Other"]`
3. Open text (optional): "Anything else we should know?"

**Onboarding effort** (one question):

1. Rating: "How easy was it to set up the app?" — labels
   `Very hard`–`Very easy`.

### Required vs optional

Toggle `Required` on each question. Required questions block the
"Next" button until answered; optional questions show a "Skip"
affordance. Open-text questions ignore the required flag if the user
submitted at least one character of whitespace, so be explicit in your
question copy.

## 4. Audience (optional)

Filter who sees the survey with device and user-property conditions, e.g.:

* **Platform** — `react_native`, `ios`, `android`, or `flutter`.
* **App version** — exact match or range. Useful for cohort studies (only ask
  users on the new build).
* **User properties** — any custom attribute you send via `identify({ properties })`.

You choose whether the conditions combine with AND or OR. If the user's
`identify()` payload doesn't include a field a filter requires, they don't see
the survey.

## Draft, publish, and activate

<Steps>
  <Step title="Save a draft (new surveys)">
    On **New survey**, click **Save draft** to create the survey without
    going live. You are redirected to the edit view where autosave takes
    over.
  </Step>

  <Step title="Autosave while editing">
    On an existing survey, edits write to the **draft** automatically.
    The header shows **Last edited** and, for active/paused surveys, an
    unpublished-change count on the status pill.
  </Step>

  <Step title="Preview">
    Use the **Preview** button (top right) to render the modal as the SDK
    will. No data is recorded — it's a static preview.
  </Step>

  <Step title="Activate or publish">
    **Draft** surveys: **Activate** copies draft → live and sets status
    to `active` (or `scheduled` if a future start date is set).
    **Active/paused** surveys: **Publish changes** copies draft → live
    without changing status. Scheduled surveys publish when they
    activate — edit the draft freely until then.
  </Step>
</Steps>

## Editing live surveys

Editing an **active** or **paused** survey is safe — you can iterate in
draft without affecting live respondents until you publish. There are two
caveats:

* **Changing the trigger key** rewrites history. Existing responses
  stay attached to the new key, which can be confusing if you're
  comparing across rollouts. Prefer creating a new survey under a
  new key (e.g. `checkout_completed_v2`).
* **Removing or renaming questions** changes the published set. Existing
  responses keep the answers they recorded, but a removed question won't appear
  in the analytics roll-up. Add a new question instead of editing an old one's
  text if you want clean before/after analytics.

In-progress SDK sessions keep the **previous live version** until
dismissed; the next trigger loads the newly published content.

## Next

<CardGroup cols={2}>
  <Card title="Survey settings" icon="gear" href="/dashboard/survey-settings">
    Behavior toggles — branding, back button, autosave, and more.
  </Card>

  <Card title="Triggers" icon="bell" href="/dashboard/triggers">
    Configure when a survey fires from the builder's Trigger tab.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/dashboard/analytics">
    Read NPS score, response counts, and the NPS trend.
  </Card>

  <Card title="Responses" icon="inbox" href="/dashboard/responses">
    Completed and partial responses, filters, and export.
  </Card>
</CardGroup>