Clarification

Intro

Sometimes we need to ask a user additional questions depending on the user answer. For example, we want to get description of an issue if a user rates our service in 3 stars or less.

Every question object has clarifying_questions key that contains a list of clarifying questions.

The ClarifyingQuestion object contains the following fields

name	type	description
question	question object	Currently, clarifying question can be text field only
choices	list	It's a list of ids or values the clarifying question need to be asked for
answers	list	A list of answers if the question was answered. Otherwise, the answers list is empty.

Asking

Here is an example of question that requires to ask the clarification question. If a user rates in 1, 2, or 3 stars, we need to ask the question with id 17 ("Why so bad?").
If a user rate in 4, we don't need to ask any clarifications. Just ask the next question from the list.
If a user rate in 5, we need to ask the question with id 18 ("Wow! We haven't got such a high score before. Could you please describe your experience?").

{
  "id": 7,
  "title": "rate using 5 stars",
  "type": "stars5",
  "category": null,
  "is_optional": false,
  "clarifying_questions": [
    {
      "question": {
        "id": 17,
        "title": "Why so bad?",
        "type": "text",
        "is_optional": true
      },
      "choices": [
        1,
        2,
        3
      ],
      "answers": []
    },
    {
      "question": {
        "id": 18,
        "title": "Wow! We haven't got such a high score before. Could you please describe your experience?",
        "type": "text",
        "is_optional": true
      },
      "choices": [
        5
      ],
      "answers": []
    }
  ],
  "answers": [],
  "choices": [
    {
      "value": 1,
      "title": "Poor"
    },
    {
      "value": 2,
      "title": "Fair"
    },
    {
      "value": 3,
      "title": "Good"
    },
    {
      "value": 4,
      "title": "Very good"
    },
    {
      "value": 5,
      "title": "Excellent"
    }
  ]
}

As you can see, clarifying question can be optional or mandatory.

Answering

In order to submit an answer for a clarifying question, send a regular post request to the /answer endpoint.
Every clarifying question contains an object with regular question that defines id, type, and other question's properties.

Question types

Here you can find examples for some types of questions.

Select

{
  "id": 2,
  "title": "your skills",
  "type": "choice",
  "category": {
    "id": 1,
    "title": "Past performance"
  },
  "is_optional": true,
  "clarifying_questions": [
    {
      "question": {
        "id": 16,
        "title": "What frameworks did you use?",
        "type": "text",
        "is_optional": true
      },
      "choices": [
        12,
        10
      ],
      "answers": []
    }
  ],
  "answers": [],
  "choice_count_min": 2,
  "choice_count_max": 4,
  "choices": [
    {
      "id": 12,
      "title": "go lang"
    },
    {
      "id": 11,
      "title": "django"
    },
    {
      "id": 10,
      "title": "python"
    }
  ]
}

5 stars rating

{
  "id": 7,
  "title": "rate using 5 stars",
  "type": "stars5",
  "category": null,
  "is_optional": false,
  "clarifying_questions": [
    {
      "question": {
        "id": 17,
        "title": "Why so bad?",
        "type": "text",
        "is_optional": true
      },
      "choices": [
        1,
        2,
        3
      ],
      "answers": []
    },
    {
      "question": {
        "id": 18,
        "title": "Wow! We haven't got such a high score before. Could you please describe your experience?",
        "type": "text",
        "is_optional": true
      },
      "choices": [
        5
      ],
      "answers": []
    }
  ],
  "answers": [],
  "choices": [
    {
      "value": 1,
      "title": "Poor"
    },
    {
      "value": 2,
      "title": "Fair"
    },
    {
      "value": 3,
      "title": "Good"
    },
    {
      "value": 4,
      "title": "Very good"
    },
    {
      "value": 5,
      "title": "Excellent"
    }
  ]
}

Choose degree between two extremes

Note the clarifying_question contains grid_questions and choices keys.
In the example below, it means you need to ask the clarifying question if a user selected "Good" or "Really good" or "Great" answering on "takes feedback well1" or "handles stress well1" grid question.

{
  "id": 9,
  "title": "How would you rate on these attributes",
  "type": "grid",
  "category": null,
  "is_optional": true,
  "clarifying_questions": [
    {
      "question": {
        "id": 18,
        "title": "Comment some attributes",
        "type": "text",
        "is_optional": true
      },
      "choices": [
        1,
        2,
        3
      ],
      "answers": [],
      "grid_questions": [
        3,
        2
      ]
    }
  ],
  "answers": [],
  "grid_questions": [
    {
      "id": 3,
      "title": "handles stress well1"
    },
    {
      "id": 2,
      "title": "takes feedback well1"
    },
    {
      "id": 1,
      "title": "attention to detail1"
    }
  ],
  "choices": [
    {
      "value": 0,
      "title": "Okay"
    },
    {
      "value": 1,
      "title": "Good"
    },
    {
      "value": 2,
      "title": "Really good"
    },
    {
      "value": 3,
      "title": "Great"
    },
    {
      "value": 4,
      "title": "Best"
    },
    {
      "value": 5,
      "title": "I don't know"
    }
  ]
}