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.
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.

The survey editor guide covers Questions, Targeting and Look & words, including autosave and Draft/Live preview. Drafts saved by browser-guided setup 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.

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:

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 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.

{
  "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 before adding other question types or translations.

Create, review and publish

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:

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.

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, 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:

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 shows its shape. Calling show() cannot substitute for that event.