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

# Survey definition and theme

> The SurveyJS JSON that a survey's definition and theme hold on the Statisfy API: structure, question types, answers, logic, validation, scores, and the limits the API checks.

A survey's `definition` holds its pages and questions. Its `theme` holds its colors and layout. Both are the JSON that the app's survey builder saves. The builder uses SurveyJS version 1.12.58, so the JSON follows the SurveyJS format of that version.

This page covers the part of SurveyJS that the Statisfy API accepts and that Statisfy uses.

> [!TIP]
>
> To get a starting point, build the survey in the app, then read it with `GET /v1/surveys/{survey_id}`. Copy its `definition` and `theme`, change them, and send them back.

## Structure

A definition is a JSON object. Put the questions in `pages[].elements`. A single-page survey can also put them in a top-level `elements` list. A `panel` groups questions in its own `elements`.

```json theme={null}
{
  "title": "Quarterly check-in",
  "showProgressBar": "top",
  "completedHtml": "<h3>Thank you for your feedback.</h3>",
  "pages": [
    {
      "name": "score",
      "elements": [
        { "type": "rating", "name": "nps_rating", "title": "How likely are you to recommend us to a friend?", "rateMin": 0, "rateMax": 10, "isRequired": true },
        { "type": "comment", "name": "nps_comment", "title": "What is the main reason for your score?" }
      ]
    },
    {
      "name": "details",
      "elements": [
        { "type": "checkbox", "name": "features", "title": "Which features do you use?", "choices": ["Reports", "Campaigns", "Digital workers"], "showOtherItem": true },
        {
          "type": "panel",
          "name": "contact",
          "title": "Can we follow up?",
          "elements": [
            { "type": "boolean", "name": "follow_up", "title": "May we contact you about your answers?" },
            { "type": "text", "name": "phone", "title": "Phone number", "inputType": "tel", "visibleIf": "{follow_up} = true" }
          ]
        }
      ]
    }
  ]
}
```

Survey-level properties that you will often use:

| Property | Purpose |
| - | - |
| `title`, `description` | The text at the top of the survey. |
| `logo` | An image URL or a `data:` URL. |
| `showProgressBar` | `off`, `top`, `bottom`, or `both`. |
| `showQuestionNumbers` | `on`, `onPage`, or `off`. |
| `completedHtml` | The HTML that shows after the respondent submits. |
| `completedHtmlOnCondition` | A list of `{ "expression": "...", "html": "..." }`. The first item whose expression is true replaces `completedHtml`. |
| `triggers` | Actions that run when an answer changes, for example `skip` or `complete`. See [Logic](#logic). |

## Rules the API checks

`POST /v1/surveys` and `PATCH /v1/surveys/{survey_id}` refuse a definition that breaks one of these rules. The app's survey builder checks the same rules. The response is `422`, with one item in `detail` for each problem. Each item's `loc` is a path such as `pages[0].elements[2].type`.

* The definition is a JSON object.
* `pages`, and each `elements` list, is a list of objects.
* Each element's `type` is one of the types in [Question types](#question-types).
* Each question has a `name`. The `name` is the key of its answer, so two questions can't have the same name. `panel`, `html`, and `image` elements don't take an answer, so they don't need a name.
* Panels nest at most 10 levels deep.
* The JSON is at most 1,000,000 characters. Inline `data:` URLs, such as an embedded logo, don't count toward this limit.
* No string contains a NUL character.

The `theme` has only the last two rules.

> [!NOTE]
>
> The API stores HTML in the definition (`html` elements, `completedHtml`) as you send it. The survey page removes scripts and other unsafe HTML when it shows the survey.

## Question types

The API accepts these 21 element types. SurveyJS ignores any other type, so a question with an unknown type never shows.

| `type` | What it shows | Main properties | Answer value |
| - | - | - | - |
| `rating` | A scale of numbers, stars, or smileys | `rateMin`, `rateMax`, `rateStep`, `rateValues`, `rateType`, `minRateDescription`, `maxRateDescription` | A number |
| `radiogroup` | One choice from a list | `choices`, `showOtherItem`, `showNoneItem`, `colCount` | The choice's value |
| `dropdown` | One choice from a menu | `choices`, `placeholder`, `showOtherItem` | The choice's value |
| `checkbox` | Many choices from a list | `choices`, `showSelectAllItem`, `showNoneItem`, `maxSelectedChoices` | A list of values |
| `tagbox` | Many choices from a menu | `choices`, `placeholder`, `searchEnabled` | A list of values |
| `ranking` | Choices that the respondent puts in order | `choices` | A list of values, first to last |
| `boolean` | Yes or no | `labelTrue`, `labelFalse`, `valueTrue`, `valueFalse` | `true` or `false` |
| `text` | One line of text | `inputType` (`text`, `email`, `number`, `date`, `tel`, `url`, …), `placeholder`, `maxLength`, `min`, `max` | A string or a number |
| `comment` | Many lines of text | `rows`, `placeholder`, `maxLength` | A string |
| `multipletext` | Many labeled text boxes | `items` (each with `name` and `title`), `colCount` | An object, keyed by item name |
| `matrix` | One choice in each row of a grid | `rows`, `columns` | An object: row value to column value |
| `matrixdropdown` | A grid with a question in each cell | `rows`, `columns` (each with `name` and `cellType`) | An object: row value to an object of cell answers |
| `matrixdynamic` | A grid where the respondent adds rows | `columns`, `rowCount`, `minRowCount`, `maxRowCount` | A list of objects, one per row |
| `paneldynamic` | A group of questions that repeats | `templateElements`, `panelCount`, `minPanelCount`, `maxPanelCount` | A list of objects, one per panel |
| `imagepicker` | One or many images | `choices` (each with `value` and `imageLink`), `multiSelect` | A value, or a list when `multiSelect` is `true` |
| `file` | A file upload | `acceptedTypes`, `allowMultiple`, `maxSize` | A list of `{ name, type, content }` |
| `signaturepad` | A signature | `penColor`, `dataFormat` | An image as a `data:` URL |
| `expression` | A value calculated from other answers | `expression`, `displayStyle` | The calculated value |
| `panel` | A group of questions | `elements`, `title`, `state` | None |
| `html` | Text or HTML | `html` | None |
| `image` | An image | `imageLink`, `altText` | None |

All questions take these properties:

| Property | Purpose |
| - | - |
| `name` | The key of the answer. Required. |
| `title` | The question text. When it is empty, SurveyJS shows the `name`. |
| `description` | Help text below the title. |
| `isRequired` | `true` makes an answer required. |
| `defaultValue` | The answer before the respondent changes it. |
| `visibleIf`, `enableIf`, `requiredIf` | Conditions. See [Logic](#logic). |
| `validators` | Answer checks. See [Validation](#validation). |
| `startWithNewLine` | `false` puts the question on the same line as the one before it. |

A choice in `choices` is a string, or an object with `value` and `text`. Use the object form when the stored value and the shown text are different:

```json theme={null}
{ "type": "radiogroup", "name": "plan", "title": "Which plan are you on?", "choices": [
  { "value": "starter", "text": "Starter" },
  { "value": "growth", "text": "Growth" }
] }
```

## Answers

`GET /v1/surveys/{survey_id}/responses` returns each response's `answers` as an object. Each key is a question's `name`, and each value has the form in the **Answer value** column. A question that the respondent skipped has no key.

```json theme={null}
{
  "nps_rating": 9,
  "nps_comment": "Setup was fast.",
  "features": ["Reports", "Campaigns"],
  "follow_up": true,
  "phone": "+1 555 0100"
}
```

When you select **Other** in a choice question, the answer is `"other"`. The text that the respondent typed is in `<name>-Comment`.

## Logic

A condition is an expression in a string. Put a question's name in braces to use its answer.

| Where | Effect |
| - | - |
| `visibleIf` on a question, panel, or page | Shows it only when the expression is true. |
| `enableIf` on a question | Makes it read-only when the expression is false. |
| `requiredIf` on a question | Makes an answer required when the expression is true. |
| `completedHtmlOnCondition` on the survey | Shows different text after submit. |
| `triggers` on the survey | When `expression` is true, `skip` goes to the question in `gotoName`, `complete` ends the survey, and `setvalue` puts `setValue` in the question `setToName`. |

```json theme={null}
{ "type": "comment", "name": "improve", "title": "What should we improve?", "visibleIf": "{nps_rating} <= 6" }
```

```json theme={null}
"triggers": [
  { "type": "complete", "expression": "{nps_rating} >= 9" }
]
```

Operators that you can use in an expression:

| Operator | Example |
| - | - |
| `=`, `!=`, `<`, `<=`, `>`, `>=` | `{nps_rating} >= 9` |
| `and`, `or`, `!` | `{follow_up} = true and {phone} notempty` |
| `empty`, `notempty` | `{nps_comment} empty` |
| `contains`, `notcontains` | `{features} contains 'Reports'` |
| `anyof`, `allof` | `{features} anyof ['Reports', 'Campaigns']` |

## Validation

`isRequired` and `validators` check an answer before the respondent can go to the next page.

```json theme={null}
{
  "type": "text",
  "name": "seats",
  "title": "How many seats do you need?",
  "inputType": "number",
  "validators": [
    { "type": "numeric", "minValue": 1, "maxValue": 10000, "text": "Enter a number from 1 to 10,000." }
  ]
}
```

| Validator `type` | Checks |
| - | - |
| `numeric` | The number is between `minValue` and `maxValue`. |
| `text` | The text length is between `minLength` and `maxLength`. |
| `email` | The text is an email address. |
| `regex` | The text matches `regex`. |
| `answercount` | The number of choices is between `minCount` and `maxCount`. |
| `expression` | The `expression` is true. |

## NPS and CSAT scores

An `NPS` or `CSAT` survey sends its score to the account's survey activity and to account health. A `CES` or `CUSTOM` survey sends no score. Statisfy finds the score in this order:

1. The question named `nps_rating` or `csat_rating`.
2. If there is no such question, the first `rating` question on the first page.

The question must be directly in `pages[].elements`, not in a panel or in a top-level `elements` list. Its answer must be a whole number. Statisfy reads the maximum score from the question's `rateMax`. When `rateMax` is not set, Statisfy uses 10, but SurveyJS shows a 1 to 5 scale. Thus, always set `rateMin` and `rateMax`.

For an NPS score, Statisfy puts the respondent in a category: 0 to 6 is a detractor, 7 or 8 is a passive, and 9 or 10 is a promoter.

Statisfy reads the comment from the question named `nps_comment`, `csat_comment`, or `comment`. Use one of these names for the reason question.

## Theme

The `theme` sets the survey's colors, background, and layout. When it is `null`, the survey uses the SurveyJS default light theme. The main properties are:

| Property | Purpose |
| - | - |
| `themeName` | The base theme, for example `default`, `sharp`, `borderless`, `flat`, `plain`, `doubleborder`, `layered`, `solid`, `threedimensional`, or `contrast`. |
| `colorPalette` | `light` or `dark`. |
| `isPanelless` | `true` removes the border around each question. |
| `backgroundImage`, `backgroundImageFit`, `backgroundOpacity` | The page background. |
| `cssVariables` | Colors, sizes, and fonts as CSS variables, for example `--sjs-primary-backcolor`. |

```json theme={null}
{
  "themeName": "default",
  "colorPalette": "light",
  "isPanelless": false,
  "cssVariables": {
    "--sjs-primary-backcolor": "#4f46e5",
    "--sjs-primary-forecolor": "#ffffff",
    "--sjs-general-backcolor-dim": "#f5f5f7"
  }
}
```

The easiest way to get a full theme is to build it in the app's **Themes** tab, then read the survey from the API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.