The diagram below shows the process of going through a survey:
answer_type
is list
, fetch possible answers from meta.source_list_url
.
To fetch the current question and give an answer, use the endpoints below.
To download the current question, make a GET request to /api/v2/surveys/{survey_id}/questions/current
.
curl -X 'GET' \
'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/current'
Response includes the question object. For more information, see the “Question object” section.
Example:
{
"id": "visit_reason",
"index": 0,
"question": {
"text": "What is the main reason for your visit?"
},
"answer_type": "multiple_choice",
"meta": {
"answers": [
{
"id": "symptoms",
"label": "I have worrying symptoms"
},
{
"id": "test-results",
"label": "I want to discuss the test results"
},
{
"id": "extend-prescription",
"label": "I want to extend my prescription"
},
{
"id": "follow-up",
"label": "I have a follow-up visit"
},
{
"id": "other",
"label": "Other"
}
]
}
}
To answer the current question, send a POST request to /api/v2/surveys/{survey_id}/questions/current
.
curl -X 'POST' \
'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/current' \
-H 'Content-Type: application/json' \
-d '{
"answer": [
{
"id": "symptoms"
}
]
}'
The transmitted value depends on the answer_type
field in the question object. For more information, see the “Answer types” section.
The response was accepted. It also returns the object of the next question.
HTTP status code: 204The response was accepted. No more questions. Survey is completed.
HTTP status code: 409The survey has been closed. It is not possible to answer a completed survey.
If you need to fetch the previous question, call the GET method on /api/v2/surveys/{survey_id}/questions/{question_index}
. The index
param is the sequence number of the question in the survey.
curl -X 'GET' \
'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/3'
To answer a previous question, call the PUT method on /api/v2/surveys/{survey_id}/questions/{question_index}
. The index
param is the sequence number of the question in the survey. The questions depend on the answers given.
If you update a previous question, the answers to the following questions will be reset.
curl -X 'PUT' \
'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/1' \
-H 'Content-Type: application/json' \
-d '{
"answer": {"id": "female"}
}'
The response was accepted. It also returns the object of the next question.
HTTP status code: 204The response was accepted. No more questions. Survey is completed.
HTTP status code: 409The survey has been closed. It is not possible to answer a completed survey.
To fetch all of the answers given in a survey, send a GET request to /api/v2/surveys/{survey_id}/questions
. The response will include a paginated list of question objects with user answers. You can limit the elements on a page using the limit
parameter:
curl -X 'GET' \
'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions' \
-H 'accept: application/json'
Maximum limit of elements per page. Default value is 10
, maximum value is 50
.
{
"self": "https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions?cursor=0",
"first": "https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions?cursor=0",
"last": "https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions?cursor=0",
"items": [
{
"id": "visit_reason",
"index": 0,
"user_answer": {
"answer": [
{
"id": "symptoms"
}
]
}
},
{
"id": "sex",
"index": 1,
"user_answer": {
"answer": {
"id": "female"
}
}
}
]
}
The question object contains the necessary information that the user needs to answer the question.
{
"id": "sex",
"index": 1,
"question": {
"text": "What is your sex?"
},
"answer_type": "choice",
"meta": {
"answers": [
{
"id": "female",
"label": "Female"
},
{
"id": "male",
"label": "Male"
}
]
},
"user_answer": {
"answer": {
"id": "female"
}
}
}
ID that identifies the question.
index (number)Ordinal number of the questions in the survey.
question (object)text (str) - Question text.
answer_type (str)The type of answer to the given question.
meta (object)answer_type
is list
. Contains URL to list values allowed in given question.
answer_type
is text
. Maximum number of characters allowed in answer.
answer_type
is number
. Minimum value of the answer.
answer_type
is number
. Maximum value of the answer.
answer_type
is symptoms
. Possible values: single
, group_single
, group_multiple
. Information on how to handle this question.
User's answer to this question, if it was given.
If meta.required
has the false
value in the question object, you can skip this question by providing null
in the user answer.
Example
{
"answer": null
}
The answer structure will be different depending on the value of answer_type
in the question object. This section describes the possible answer types.
{
"id": "visit_reason",
"index": 0,
"question": {
"text": "What is the main reason for your visit?"
},
"answer_type": "multiple_choice",
"meta": {
"answers": [
{
"id": "symptoms",
"label": "I have worrying symptoms"
},
{
"id": "test-results",
"label": "I want to discuss the test results"
},
{
"id": "extend-prescription",
"label": "I want to extend my prescription"
},
{
"id": "follow-up",
"label": "I have a follow-up visit"
},
{
"id": "other",
"label": "Other"
}
]
}
}
{
"answer": [
{
"id": "other"
},
{
"id": "test-results"
}
]
}
Object list. Each object must contain an id
that coincides with the possible values defined in the meta.answers
field in the question object.
{
"id": "sex",
"index": 1,
"question": {
"text": "What is your sex?"
},
"answer_type": "choice",
"meta": {
"answers": [
{
"id": "female",
"label": "Female"
},
{
"id": "male",
"label": "Male"
}
]
}
}
{
"answer": {
"id": "female"
}
}
Object must contain an id
that coincides with the possible values defined in the meta.answers
field of the question object. You can only choose one possible option.
{
"id": "age",
"index": 2,
"question": {
"text": "How old are you?"
},
"answer_type": "number",
"meta": {
"min_value": 18,
"max_value": 130
}
}
{
"answer": 30
}
Integer number from the range defined in the question object (must be between meta.min_value
and meta.max_value
).
{
"id": "symptoms",
"index": 5,
"question": {
"text": "Add your symptoms"
},
"answer_type": "list",
"meta": {
"source_list_url": "/v2/knowledge/symptoms?age=39&sex=female&language=en"
}
}
{
"self": "https://<INSTANCE_URL>/api/v2/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=5",
"first": "https://<INSTANCE_URL>/api/v2/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=0",
"prev": "https://<INSTANCE_URL>/api/v2/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=4",
"next": "https://<INSTANCE_URL>/api/v2/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=6",
"last": "https://<INSTANCE_URL>/api/v2/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=330",
"items": [
{
"id": "s_582",
"name": "Anxiety attack"
},
{
"id": "s_1800",
"name": "Appendix removal in the past"
},
{
"id": "s_6",
"name": "Appetite for salty foods"
},
{
"id": "s_1010",
"name": "Apraxia"
},
{
"id": "p_254",
"name": "Arm injury"
}
]
}
{
"answer":[
{
"id":"s_1096"
}
]
}
Object list. Each object must contain an ID that coincides with the possible values defined in the additional endpoint defined in meta.source_list_url
field. To fetch possible values, make a GET request to the endpoint defined in the meta.source_list_url
field. Each object in the list required id
field.
To answer a question with answer_type
equal to list
you must call one of the knowledge endpoints. These endpoints provide information about specialists, symptoms, etc.
List of supported endpoints
To be able to search for elements in a list, you may pass the query
parameter in URL to filter elements by name.
{
"id": "comment",
"index": 10,
"question": {
"text": "Just one last thing, add anything else that you would like your doctor to know."
},
"answer_type": "text",
"meta": {
"max_length": 400
}
}
{
"answer": "Example message to doctor"
}
A string. Cannot be longer than the value defined in the meta.max_length
field of the question object.
{
"id": "risk_factors",
"index": 3,
"question": {
"text": "Please check all the statements below that apply to you"
},
"answer_type": "symptoms",
"meta": {
"component": "group_multiple",
"answers": [
{
"id": "p_7", # id
"name": "Obesity",
"choices": [
{
"id": "present", # choice_id
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
},
{
"id": "p_9",
"name": "Diagnosed hypertension",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
}
]
}
}
{
"answer":[
{"id": "p_7", "choice_id": "present"},
{"id": "p_9", "choice_id": "absent"}
]
}
Object list. Each object must contain an id
and choice_id
that coincides with the possible values defined in the meta.answers
field in the question object. Answers should be handled in different ways depending on the meta.component
present:
group_multiple
component represents questions about a group of related options where each group of them must be selected.
choice_id
.
group_single
component represents questions about a group of related but mutually exclusive options, of which the user should choose exactly one.