---
title: Your first survey
description: Create, publish and verify a complete survey using the dashboard or CLI.
url: https://docs.userreason.com/get-started/first-prompt/
updated: 2026-11-09
---

# Your first survey

Start with a development site and a page-load survey. This lets you check display and response delivery before adding event definitions or audience conditions.

The app calls these surveys; the CLI keeps its existing `prompt` commands and JSON field names.

## In the dashboard

1. Open your development site in the [dashboard](https://dash.userreason.com).
2. Create a survey with one rating question and an optional text follow-up.
3. Choose everyone as the audience, page load as the trigger, and 100% sampling.
4. Set a maximum of one response per visitor, review the content, and publish.
5. Reload the app in a fresh private browsing session. Answer the survey, then inspect its responses.

Dismissal and frequency rules can prevent repeated display while testing. Use a fresh visitor rather than changing production limits. See [Troubleshooting](https://docs.userreason.com/get-started/troubleshooting/index.md).

The [survey editor guide](https://docs.userreason.com/prompts/editor/index.md) covers Questions, Targeting and Look & words, including autosave and Draft/Live preview. Drafts saved by [browser-guided setup](https://docs.userreason.com/get-started/browser-setup/index.md) also need your review and explicit publication.

## The same flow with the CLI

Install the CLI and sign in. It requires Node 22.12 or newer.

```sh
npm install -g @userreason/cli
userreason login --open
userreason workspace list
```

Replace `WORKSPACE_UUID` and `SITE_UUID` below with your real IDs. List sites, then request the permissions needed to read, edit and publish surveys:

```sh
userreason site list --workspace WORKSPACE_UUID
userreason grant request --workspace WORKSPACE_UUID --site SITE_UUID --scope site:read --scope survey:write --scope campaign:publish --wait
```

Open the printed approval URL and approve the requested access. Signing in alone does not authorize survey management. The [CLI reference](https://docs.userreason.com/cli/index.md) explains grants and credentials.

## Save a complete definition

Save this as `prompt.json`. This is the full file, including required null values and frequency settings. The enrollment epoch is an identifier you choose; keep it unchanged during ordinary edits.

```json title="prompt.json"
{
  "schema_version": 1,
  "name": "First experience",
  "content": {
    "schema_version": 1,
    "title": "How was your first experience?",
    "description": null,
    "questions": [
      {
        "id": "experience",
        "kind": "rating",
        "prompt": "How easy was it to get started?",
        "required": true,
        "min": 1,
        "max": 5,
        "min_label": "Difficult",
        "max_label": "Easy"
      },
      {
        "id": "improve",
        "kind": "text",
        "prompt": "What could we improve?",
        "required": false,
        "max_length": 2000
      }
    ],
    "thank_you": "Thank you for helping us improve."
  },
  "rules": {
    "schema_version": 1,
    "audience": { "type": "always" },
    "triggers": [{ "type": "page_load" }],
    "frequency": { "mode": "site_default" }
  },
  "sampling_percent": 100,
  "priority": 0,
  "enrollment_epoch": "first-experience-v1"
}
```

See [Survey definition](https://docs.userreason.com/prompts/definition/index.md) before adding other question types or translations.

## Create, review and publish

```sh
userreason prompt create --workspace WORKSPACE_UUID --site SITE_UUID --file prompt.json --json
```

Open the returned `links.edit` to review the saved draft in the dashboard. Copy the returned `prompt_id` and use it in place of `PROMPT_UUID`:

```sh
userreason prompt get PROMPT_UUID --workspace WORKSPACE_UUID --site SITE_UUID --json
```

Review the definition and copy its current `revision`. Replace `CURRENT_REVISION` below with that value. Revisions change after mutations; do not assume the revision is always `1`.

```sh
userreason prompt publish PROMPT_UUID --workspace WORKSPACE_UUID --site SITE_UUID --revision CURRENT_REVISION --json
```

Reload your app after publishing. Its initialized SDK observes the page-load trigger automatically. With the site's default [frequency](https://docs.userreason.com/prompts/targeting/index.md#frequency), a survey you saw and left alone comes back after 7 days and one you answered does not come back; to see it again while testing, use a fresh private browsing window. After submitting a response, read it with:

```sh
userreason prompt responses PROMPT_UUID --workspace WORKSPACE_UUID --site SITE_UUID --limit 10 --json
```

Use `links.results` or `links.responses` from the survey result to open its results or answers in the dashboard.

## Change the survey later

Edit the complete JSON file, read the current revision, run `prompt update` with that revision, review, and publish using the new revision. Updates stay in the draft until published. Pause a live survey when you need to stop delivery immediately.

For feedback after a business action, define the event on the site and replace the page-load trigger with an event trigger. [Targeting](https://docs.userreason.com/prompts/targeting/index.md) shows its shape. Calling `show()` cannot substitute for that event.