Navigating question flows

Basic flow

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

Step 1. Fetch current question.
Step 2. If answer_type is list, fetch possible answers from meta.source_list_url.
Step 3. Provide a user answer to the current question.
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

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/mgp/v1/surveys/{survey_id}/questions/current.

cURL

curl "https://api.infermedica.com/api/mgp/v1/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"
      }
    ],
    "has_rationale": false
  }
}

Give your answer

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

cURL

curl "https://api.infermedica.com/api/mgp/v1/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/mgp/v1/surveys/{survey_id}/questions/{question_index}. The index param is the sequence number of the question in the survey.

cURL

curl "https://api.infermedica.com/api/mgp/v1/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/3" \
  -X "GET"

Answering previous questions

To answer a previous question, call the PUT method on /api/mgp/v1/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://api.infermedica.com/api/mgp/v1/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/mgp/v1/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://api.infermedica.com/api/mgp/v1/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions" \
  -X "GET"

Request parameters in query

limit (number, optional)

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

cursor (number, optional)

Page number.

Example response

JSON

{
  "self": "https://api.infermedica.com/api/mgp/v1/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions?cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions?cursor=0",
  "last": "https://api.infermedica.com/api/mgp/v1/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"
        }
      }
    }
  ]
}

Answering the Plan Survey

To answer the Plan Survey (similar to the Intent Survey but after the finished interview), send a POST request to /api/mgp/v1/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/intent_after.

A value can be filled in for the form_of_contact field if kind_of_care is set to either primary or specialist. If kind_of_care is set to anything other than primary or specialist, status code 422 - Unprocessable entity will be returned.

The following values are possible for the kind_of_care field:

doing_nothing
self-care
primary
specialist
allied
urgent
emergency
ambulance
unknown

The following values are possible for the form_of_contact field:

in_person
teleconsultation
helpline
application
unknown

cURL

curl "https://api.infermedica.com/api/mgp/v1/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/intent_after" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{
    "kind_of_care": {"id": "specialist"},
    "form_of_contact": {"id": "application"}
  }'

Responses

HTTP status code: 200

The response was accepted. No further processing is needed.

HTTP status code: 422

Request was unprocessable. It could be due to:

A forbidden combination of the kind_of_care / form_of_contact fields, showing the error message: Answers do not match intent survey flow.
An invalid value in either the kind_of_care / form_of_contact field, showing an error message like: The Specified id (1a815f9c-8fe2-4a31-9728-550b92c4b077) is incorrect.

Rationale current question

To fetch the rationale for the current question, make a GET request to /api/mgp/v1/surveys/{survey_id}/questions/current/rationale.

cURL

curl "https://api.infermedica.com/api/mgp/v1/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/current/rationale" \
  -X "GET"

Responses

HTTP status code: 200

Rationale response is an object comprised of the following attributes:

message: string - a user-facing message that can be displayed to the patient
data: object - rationale raw data, contains:
- type: string - a well defined code (r0-r6)
- observation_params: list[string] - a list of observation IDs, relevant to prioritizing a question
- condition_params: list[string] - a list of condition IDs, relevant to prioritizing a question

For more information about "data", see the “Engine API - Rationale” section on the Engine API page. Depending on the question type, the whole object or just a message can be returned.

Example: Questions from the dynamic part of the survey will return all of the data:

JSON

{
    "data": {
      "type": "r6",
      "observation_params": [
          {
              "id": "s_44",
              "name": "Joint pain",
              "common_name": "Joint pain"
          }
      ],
      "condition_params": []
    },
    "message": "We are asking this question to learn more about your Joint pain."
}

Example: Static questions that have rationale just return a message:

JSON

{
    "message": "We are asking this question to better understand the needs and motivations of patients using this checkup. Your answer will help us learn and improve our product."
}

HTTP status code: 404

Rationale not found - Survey or rationale not found

Fetch Rationale for previous question

If you need to fetch the rationale for a previous question, make a GET request to /api/mgp/v1/surveys/{survey_id}/questions/{question_index}/rationale. The question_index param is the sequence number of the question in the survey.

cURL

curl "https://api.infermedica.com/api/mgp/v1/surveys/1a815f9c-8fe2-4a31-9728-550b92c4b077/questions/5/rationale" \
  -X "GET"

Responses

HTTP status code: 200

Same as “Rationale current question” above.

HTTP status code: 404

Rationale not found - Survey or rationale not found

HTTP status code: 409

Cannot fetch question - Question does not exist

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"
      }
    ],
    "has_rationale": false
  },
  "user_answer": {
    "answer": {
      "id": "female"
    }
  }
}

Fields

id (str)

ID that identifies the question.

index (number)

Ordinal number of the questions in the survey (0-based index).

question (object)

text (str) – Question text.

answer_type (str)

The type of answer to the given question.

meta (object)

has_rationale (bool) – Indicates whether the question may include an explanation or reasoning that can be retrieved using the rationale endpoint.
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.
evidence_id (str, optional) - Specified if answer_type is duration. Evidence id .
alerts (list, optional) – A list of alerts generated during interview processing, with each alert following the Alert schema. Currently the only supported alert type is soft_stop, which is used when the interview identifies high-risk symptoms associated with suicide and enables the application to implement the appropriate safety measures for those situations. The Alert schema includes the following properties:
- type (str) – The type of alert, currently limited to soft_stop.
- reasons (list) – A list of reasons for the alert, indicating detected risk factors. Possible string values include:
  - suicide_attempt – Detected history of suicide attempts.
  - suicidal_intent – Detected signs of intent to harm oneself.
  - suicidal_thoughts – Detected signs of suicidal thoughts.

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"
      }
    ],
    "has_rationale": false
  }
}

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"
      }
    ],
    "has_rationale": false
  }
}

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.

Age

Example question object

JSON

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

Example answer

JSON

{
  "answer": {
    "value": 30,
    "unit": "year"
  }
}

Answer body

answer (object)

value (number) - A value consisting of an integer within the range defined in the question object (must be between meta.min_value and meta.max_value).
unit (str) - A unit of age. It can be year or month.

List

Example question object

JSON

{
  "id": "symptoms",
  "index": 5,
  "question": {
    "text": "Add your symptoms"
  },
  "answer_type": "list",
  "meta": {
    "source_list_url": "/v1/knowledge/symptoms?age=39&sex=female&language=en",
    "has_rationale": false
  }
}

Example data from knowledge endpoint

JSON

{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=5",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=0",
  "prev": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=4",
  "next": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?age=31&sex=male&language=en&limit=5&cursor=6",
  "last": "https://api.infermedica.com/api/mgp/v1/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/mgp/v1/knowledge/symptoms
/api/mgp/v1/knowledge/chronic_diseases
/api/mgp/v1/knowledge/specialists
/api/mgp/v1/knowledge/hospitalizations

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,
    "has_rationale": false
  }
}

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"
          }
        ]
      }
    ],
    "has_rationale": false
  }
}

Example answer

JSON

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

Answer body

answer (list)

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.

Duration

ℹ️

Question duration type is not enabled by default. It can be enabled during the initial instance configuration or any time afterwards.

Example question object

JSON

{
  "id": "interview",
  "index": 12,
  "question": {
    "text": "How long have you had abdominal pain?"
  },
  "answer_type": "duration",
  "meta": {
    "component": "duration",
    "evidence_id": "s_13",
    "has_rationale": false
  }
}

Example answer

JSON

{
  "answer": [
    {
      "id": "s_13",
      "duration": {
        "value": 5,
        "unit": "day"
      }
    }
  ]
}

Answer body

answer (list)

Object list with one element only. Object must contain an id that coincides with meta.evidence_id field in the question object and duration object with value and unit.

Possible duration units: minute, hour, day, week

Surveys Fetching Results