Working with questionnaires
There are 2 endpoints to work with questionnaires.
GET /v1/refchecks/{refcheck_id}/questions/?token={token}to get the list of questions associated with the refcheckPOST /v1/answers/?token={token}orPOST /v1/answers/?is_self_reference=1to submit an answer
The list of questions is a list of objects with several common fields and some additional fields. The set of the additional
fields depend on the question type field.
The common question fields are listed below
| field | description |
|---|---|
| id | id of the question. you will use the field to submit an answer |
| title | directly the question |
| type | set of the optional fields depends on the question type |
| answers | a list of current user's (identified by token query param) answers. the list is empty if the current user didn't answer the question. |
| is_optional | bool, defines is the question can be skipped |
| clarifying_questions | a list of questions that need to be asked in some cases. read more about clarification |
Here is the example of the refcheck questions list
[
{
"id": 1,
"title": "What is your name?",
"type": "text",
"is_optional": true,
"answers": [
{
"id": 58,
"question": 1,
"ref_check": 50,
"text": "My name is Bob"
}
]
},
{
"id": 7,
"title": "Rate working experience using 5 stars",
"type": "stars5",
"is_optional": false,
"answers": [],
"choices": [
{
"value": 1,
"title": "Poor"
},
{
"value": 2,
"title": "Fair"
},
...
{
"value": 5,
"title": "Excellent"
}
]
},
{
"id": 13,
"title": "What are your skills?",
"type": "choice",
"is_optional": false,
"answers": [],
"choice_count_min": 2,
"choice_count_max": 5,
"choices": [
{
"id": 9,
"title": "html"
},
...
{
"id": 4,
"title": "django"
}
]
}
]
In order to submit a response, you need to send a POST request to /v1/answers/.
You need to pass a token query param if a reference answers.
If a candidate answers, you need to pass is_self_reference query param with Authorization header.
The payload depends on the question type you submit the answer for.
There are following common fields:
| field | description |
|---|---|
| question | question id you submit the answer for |
| ref_check | ref_check id you submit the answer for |
| client_key | a string. ask for detailed info about client_key |
| duration_sec | how many seconds a user spent answering the question |
Additional fields are described in question types description.
How to calculate duration_sec
A value of the duration_sec should be calculated on front end. It' nice if you can pause a stopwatch when a browser
window is not active.
Question types
Text field
[TODO: UI screen]
This type of question doesn't contain additional fields.
Question example
Answer payload example
{
"question": 1,
"ref_check": 2,
"text": "My name is...",
"client_key": "client-key",
"duration_sec": 24
}
Select
[TODO: UI screen]
Additional fields
| field | description |
|---|---|
| choice_count_min | Determines a minimal amount of choices must be selected for a valid answer |
| choice_count_max | Max amount of choices can be selected |
| choices | list of objects with id and title fields |
Question example
{
"id": 13,
"title": "What are your skills?",
"type": "choice",
"is_optional": true,
"answers": [],
"choice_count_min": 2,
"choice_count_max": 5,
"choices": [
{
"id": 9,
"title": "html"
},
{
"id": 5,
"title": "python"
},
{
"id": 4,
"title": "django"
}
]
}
Answer payload example
{
"question": 13,
"ref_check": 2,
"choices": [9, 5],
"client_key": "client-key",
"duration_sec": 24
}
5 stars rating
[TODO: UI screen]
Additional fields
| field | description |
|---|---|
| choices | list of objects with value and title fields |
Question example
{
"id": 7,
"title": "Rate working experience using 5 stars",
"type": "stars5",
"is_optional": true,
"answers": [],
"choices": [
{
"value": 1,
"title": "Poor"
},
{
"value": 2,
"title": "Fair"
},
{
"value": 3,
"title": "Good"
},
{
"value": 4,
"title": "Very good"
},
{
"value": 5,
"title": "Excellent"
}
]
}
Answer payload example
Choose degree between two extremes
[TODO: UI screen]
Additional fields
| field | description |
|---|---|
| extreme_left | title of the left extreme |
| extreme_right | title of the right extreme |
| choices | list of objects with value and title fields |
Question example
{
"id": 8,
"title": "how reasonable is your workload",
"type": "extremes",
"is_optional": true,
"answers": [],
"extreme_left": "very unreasonable1",
"extreme_right": "very reasonable",
"choices": [
{
"value": 0,
"title": "Much more"
},
{
"value": 1,
"title": "About the same"
},
{
"value": 2,
"title": "Much more"
}
]
}
Answer payload example
Multi-question grid
[TODO: UI screen]
Additional fields
| field | description |
|---|---|
| grid_questions | list of objects with id and title fields |
| choices | list of objects with value and title fields |
Question example
{
"id": 9,
"title": "How would you rate on these attributes?",
"type": "grid",
"is_optional": true,
"answers": [],
"grid_questions": [
{
"id": 3,
"title": "handles stress well1"
},
{
"id": 2,
"title": "takes feedback well"
},
{
"id": 1,
"title": "attention to detail"
}
],
"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"
}
]
}
Answer payload example