Skip to main content
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.
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.
Survey-level properties that you will often use:

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.
  • 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.
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. All questions take these properties: 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:

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.
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.
Operators that you can use in an expression:

Validation

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

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