NPS JSON Reference

Version 2.0

 The JSON Reference is designed to document the structure of the JSON configuration files that the Qrvey API consumes to produce an NPS (Net Promoter Score) survey. This document is focused on the structure and content of the “questions” object.

 

Document Organization

 This document specifically addresses the JSON structure associated with the variety of questions that the developer may include in the survey.

There are essentially three sections to this reference; the JSON overview of the “questions” object related to an NPS survey, a table that covers the available objects, properties and values, and JSON snippets and result images for each question type and option.

The Appendix presents the overall schema for the JSON file associated with an NPS survey.

 

Questions Object Overview

The questions object contains a data array of the questions comprising the NPS survey. An NPS survey may only have two questions; 1) an NPS score (required) and 2) a short text feedback question. The survey architect can make the feedback question required or optional or eliminated altogether.

Note: When the NPS score is analyzed, the responses are grouped into “detractors” (0-6), “passive” (7-8), and “promoters” (9-10). The analysis may be further refined by searching and filtering the feedback responses.

Following is a typical code snippet of the questions and options used in an NPS survey.

 

       "questions": {
        "data": [
            {
                "text": "Qrvey",
                "type": "NPS_SCORE",
                "id": "J96TSRYZ",
                "answers": [
                    {
                        "answer": "NPSSCORE"
                    }
                ],
                "question": "main",
                "time": 10
            },
            {
                "text": "Could you please explain your 
                         choice? Thank you!",
                "type": "NPS_FEEDBACK",
                "id": "3A75GU9N",
                "answers": [
                    {
                        "answer": "NPSFEEDBACK"
                    }
                ],
                "question": "optional",
                "time": 15
            }
        ]
    }
  

 

 

Properties and Values for Each Question

 Each question object is defined by common properties. The table below provides general information about each property and value. The Required column indicates whether the property is required for the question object. Some properties are required based on the question type and will be documented in the individual question sections.

Property

Value

Required

“id”

Any plain text that uniquely identifies the question object. The id value must be unique throughout the JSON file.

Yes

“text”

The question text to be displayed in the survey.

Yes

“type”

The question type. Valid values include: “NPS_SCORE”, “NPS_FEEDBACK”

Yes

“answers”

Usually an array of answerid and answer property pairs, for the NPS survey the response presentation is fixed. This array serves as a structural placeholder.

“question”

Determines whether the question is required to be answered when the survey is taken: Valid values include: “main”, “optional”

Yes

“time”

The expected elapsed time to respond to the question

Yes

 

 

Question Samples

Following are JSON configuration snippets for each type of question as well as an Image of how the question appears in a survey.

 

“NPS_SCORE”

 

An NPS_SCORE question presents the user with a rating scale from 0 to 10 that the user clicks to set the value.

The question text is fixed with the exception of the topic “text”. In our example, the word “Qrvey” is inserted into the static question “How likely are you to recommend ______ to a friend or a colleague?”

The scale is annotated with “Not Likely=0” and “Very Likely=10” to guide the user in their choice.

An NPS_SCORE question is always required in an NPS survey. The “question” property value must be set to “main”.

The “id” property value must be unique for the survey.

Typical NPS_SCORE Question Code Example

 

            {
                text: Qrvey,
                type: NPS_SCORE,
                id: J96TSRYZ,
                answers: [
                    {
                        answer: NPSSCORE
                    }
                ],
                question: main,
                time: 10
            }
  

 

Sample: Required NPS_SCORE question

 

 “NPS_FEEDBACK”

An NPS_FEEDBACK question allows the user to provide additional comments that may explain their choice of NPS score. The user is limited to a maximum of 176 characters in their response.

An NPS survey is not required to have an NPS_FEEDBACK question.

The survey architect controls the feedback question text by setting the value of the “text” property.

If the survey architect decides to solicit feedback, the question may be required or optional. Setting the “question” property value to “main” will make the question response required. If the “question” property value is set to “optional”, the user may skip the question.

The “id” property value must be unique for the survey.

 

An Optional NPS_FEEDBACK Question Code Example:

         {
                text: Could you please explain your
                      choice? Thank you!,
                type: NPS_FEEDBACK,
                id: 3A75GU9N,
                answers: [
                    {
                        answer: NPSFEEDBACK
                    }
                ],
                question: optional,
                time: 15
            }
  

 

Sample: An optional NPS_FEEDBACK question

Appendix – NPS Survey JSON Schema

    {
  $schema: http://json-schema.org/draft-04/schema#,
  type: object,
  properties: {
    name: {type: string},
    description: {type: string},
    customStyle: {type: object,
      properties: {
        name: {type: string},
        style: {type: object,
          properties: {
            mainFont: {type: string},
            imgSize: {type: integer},
            questionFont: {type: string},
            answerFont: {type: string},
            background: {type: string},
            textFieldBackground: {type: string},
            buttons: {type: string},
            main: {type: string}
          },
          required: [mainFont,imgSize, questionFont,answerFont,
                     background,textFieldBackground,buttons,main]
        },
        userid: {type: string},
        styleid: {type: string}
      },
      required: [name,style,userid,styleid]
    },
    questions: {type: object,
      properties: {
        data: {type: array,
          items: {type: object,
            properties: {
              text: {type: string},
              type: {type: string},
              id: {type: string},
              answers: {type: array,
                items: {type: object,
                  properties: {
                    answer: {type: string}
                  },
                  required: [answer]
                }
              },
              question: {type: string},
              time: {type: integer}
            },
            required: [text,type,id,answers, question,time]
          }
        }
      },
      required: [data]
    },
    totalQuestions: {type: integer},
    totalTime: {“type: integer},
    tempStyle: {type: object,
      properties: {
        name: {type: string},
        style: {type: object,
          properties: {
            mainFont: {type: string},
            imgSize: {type: integer},
            questionFont: {type: string},
            answerFont: {type: string},
            background: {type: string},
            textFieldBackground: {type: string},
            buttons: {type: string },
            main: {type: string}
          },
          required: [mainFont,imgSize,questionFont,answerFont,
                     background,textFieldBackground,buttons,main]
        },
        userid: {type: string},
        styleid: {type: string}
      },
      required: [name,style,userid,styleid]
    },
    thankYouPage: {type: object,
      properties: {
        title: {type: string},
        content: {“type: string},
        link: {type: string}
      },
      required: [title,content,link]
    },
    duration: {type: object,
      properties: {
        number: {“type: integer},
        period: {type: string},
        neverExpires: {type: boolean}
      },
      required: [number,period,neverExpires]
    },
    results_visibility: {type: string},
    respondent_email: {type: string}
  },
  required: [name,description,customStyle,questions,
             totalQuestions,totalTime,tempStyle,thankYouPage,
             duration,results_visibility,respondent_email
  ]
}