Documentation
API: Intake
Navigating Question Flows

Navigating question flows

Basic flow

The diagram below shows the process of going through a survey:

  1. Step 1. Fetch current question.
  2. Step 2. If answer_type is list, fetch possible answers from meta.source_list_url.
  3. Step 3. Provide a user answer to the current question.
  4. Step 4. API returns status code 204 if the survey is completed. If the status code is 200, the response will contain the next question and you should go back to step 2.

Survey not found

alt_text

Survey completed

Endpoints

To fetch the current question and give an answer, use the endpoints below.

Current question

To download the current question, make a GET request to /api/v2/surveys/{survey_id}/questions/current.

cURL
curl 'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/current' \
  -X 'GET'

Response

Response includes the question object. For more information, see the “Question object” section.

Example:

JSON
{
  "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"
      }
    ]
  }
}

Give your answer

To answer the current question, send a POST request to /api/v2/surveys/{survey_id}/questions/current.

cURL
curl 'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/current' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -d '{
    "answer": [
      {
        "id": "symptoms"
      }
    ]
  }'

Request parameters in body

answer (required)

The transmitted value depends on the answer_type field in the question object. For more information, see the “Answer types” section.

Responses

HTTP status code: 200

The response was accepted. It also returns the object of the next question.

HTTP status code: 204

The response was accepted. No more questions. Survey is completed.

HTTP status code: 409

The survey has been closed. It is not possible to answer a completed survey.

Fetch previous question

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
curl 'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/3' \
  -X 'GET'

Answering previous questions

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
curl 'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/1' \
  -X 'PUT' \
  -H 'Content-Type: application/json' \
  -d '{
    "answer": {"id": "female"}
  }'

Responses

HTTP status code: 200

The response was accepted. It also returns the object of the next question.

HTTP status code: 204

The response was accepted. No more questions. Survey is completed.

HTTP status code: 409

The survey has been closed. It is not possible to answer a completed survey.

List answers

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
curl 'https://<INSTANCE_URL>/api/v2/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions' \
  -X 'GET' \
  -H 'Accept: application/json'

Request parameters in query

limit (number, optional)

Maximum limit of elements per page. Default value is 10, maximum value is 50.

Example response

JSON
{
  "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"
        }
      }
    }
  ]
}

Question object

The question object contains the necessary information that the user needs to answer the question.

Example question

JSON
{
  "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"
    }
  }
}

Fields

id (str)

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)

  • answers (list, optional) – Possible answers.
  • required (bool, optional) – Is the answer required? If not specified, the question requires an answer.
  • source_list_url (str, optional) – Specified if answer_type is list. Contains URL to list values allowed in given question.
  • max_length (number, optional) – Specified if answer_type is text. Maximum number of characters allowed in answer.
  • min_value (number, optional) – Specified if answer_type is number. Minimum value of the answer.
  • max_value (number, optional) – Specified if answer_type is number. Maximum value of the answer.
  • component (str, optional) – Specified if answer_type is symptoms. Possible values: single, group_single, group_multiple. Information on how to handle this question.

user_answer (object, optional)

User's answer to this question, if it was given.

Optional questions

If meta.required has the false value in the question object, you can skip this question by providing null in the user answer.

Example

JSON
{
  "answer": null
}

Answer types

The answer structure will be different depending on the value of answer_type in the question object. This section describes the possible answer types.

Multiple choice

Example question object

JSON
{
  "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"
      }
    ]
  }
}

Example answer

JSON
{
  "answer": [
    {
      "id": "other"
    },
    {
      "id": "test-results"
    }
  ]
}

Answer body

answer (list)

Object list. Each object must contain an id that coincides with the possible values defined in the meta.answers field in the question object.

Choice

Example question object

JSON
{
  "id": "sex",
  "index": 1,
  "question": {
    "text": "What is your sex?"
  },
  "answer_type": "choice",
  "meta": {
    "answers": [
      {
        "id": "female",
        "label": "Female"
      },
      {
        "id": "male",
        "label": "Male"
      }
    ]
  }
}

Example answer

JSON
{
  "answer": {
     "id": "female"
   }
}

Answer body

answer (object)

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.

Number

Example question object

JSON
{
  "id": "age",
  "index": 2,
  "question": {
    "text": "How old are you?"
  },
  "answer_type": "number",
  "meta": {
    "min_value": 18,
    "max_value": 130
  }
}

Example answer

JSON
{
  "answer": 30
}

Answer body

answer (number)

Integer number from the range defined in the question object (must be between meta.min_value and meta.max_value).

List

Example question object

JSON
{
  "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"
  }
}

Example data from knowledge endpoint

JSON
{
  "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"
    }
  ]
}

Example answer

JSON
{
  "answer": [
    {
      "id":"s_1096"
    }
  ]
}

Answer body

answer (list)

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.

Knowledge endpoints

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

  • /api/v2/knowledge/symptoms
  • /api/v2/knowledge/chronic_diseases
  • /api/v2/knowledge/specialists
  • /api/v2/knowledge/hospitalizations
  • /api/v2/knowledge/drugs

To be able to search for elements in a list, you may pass the query parameter in URL to filter elements by name.

Text

Example question object

JSON
{
  "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
  }
}

Example answer

JSON
{
  "answer": "Example message to doctor"
}

Answer body

answer (str)

A string. Cannot be longer than the value defined in the meta.max_length field of the question object.

Symptoms

Example question object

JSON
{
  "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"
          }
        ]
      }
    ]
  }
}

Example answer

JSON
{
  "answer":[
    {"id": "p_7", "choice_id": "present"},
    {"id": "p_9", "choice_id": "absent"}
  ]
}

Answer body

answer (str)

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 – the group_multiple component represents questions about a group of related options where each group of them must be selected.
  • single – when the user answers a single component, exactly one object with the ID of the item and selected choice_id.
  • group_single – the group_single component represents questions about a group of related but mutually exclusive options, of which the user should choose exactly one.
SurveysFetching Survey Results