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.
Structure
A definition is a JSON object. Put the questions inpages[].elements. A single-page survey can also put them in a top-level elements list. A panel groups questions in its own elements.
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 eachelementslist, is a list of objects.- Each element’s
typeis one of the types in Question types. - Each question has a
name. Thenameis the key of its answer, so two questions can’t have the same name.panel,html, andimageelements 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.
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.
"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.Validation
isRequired and validators check an answer before the respondent can go to the next page.
NPS and CSAT scores
AnNPS 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:
- The question named
nps_ratingorcsat_rating. - If there is no such question, the first
ratingquestion on the first page.
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
Thetheme sets the survey’s colors, background, and layout. When it is null, the survey uses the SurveyJS default light theme. The main properties are: