Surveys

Overview

To collect patient information, a survey instance must be created using the /survey endpoint. Each survey is represented by a unique generated ID. Using this ID, it's possible to manage the survey, retrieve the questions assigned to the survey, etc.

Creating surveys

To create a survey, send a POST request to the /api/v2/survey endpoint.

cURL

curl 'https:///api/v2/surveys' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -d '{
    "patient": {
      "id": "65ec46fd-4069-4102-913e-4af48cb09be6"
    }
  }'

Request parameters in body

patient (object, required)

id (str, required) – the unique patient identifier from the client system
sex (str, optional) – patient's biological sex; can only be one of two possible values: female and male
age (object, optional):
- type (str) – this attribute is optional and the default value is year. Currently supported values: year
- value (integer, required) – a numeric value that represents age
email (str, optional) – patient's email
phone (str, required) – patient's phone number. Phone numbers must include international code. Example: +11231231234
birth_date (date, optional) – patient's date of birth, date format: YYYY-MM-DD
full_name (str, optional) – patient’s full name

sections (List[str], optional)

Sections allow you to define which questions are to be asked during the survey. List of string values; allowed options include: dynamic, visit_reason, risk_factors, chronic_diseases, specialist, hospitalization, allergies, message_to_doctor, drugs. If not specified during the survey, all sections will be included.

Note: section order cannot be changed.

visit_reason (List[VisitReason], optional)

Allows you to create a survey with a predetermined reason for the visit. If VisitReason has been provided, the visit reason at the start of the survey will be skipped.

VisitReason

id (str, required) – possible values: "symptoms", "test_results", "prescription_extension", "follow_up", "other".

evidence (List[Evidence], optional)

Allows initial evidence to be provided for the examination. If the evidence has been provided, the dynamic questions will be skipped.

Evidence

id (str, required) – The id attribute indicates an observed symptom or risk factor.
choice_id (str, required) – The choice_id attribute represents the state of given evidence and can have one of 3 values: present, absent or unknown. Please note that absent and unknown cannot be used interchangeably, as their mathematical meanings are different.
source (str, optional) – This allows the user to mark the exact stage of the interview that the given evidence was sent at. Thanks to this, the engine can provide more relevant interviews and, as a result, a better final list of most probable conditions as well as improved triage recommendations. Possible values:
- "source": "initial" – evidence reported by user,
- "source": "suggest" – evidence from /suggest endpoint,
- no value – for evidence gathered during the interview, the source attribute should be entirely omitted.

Example:

JSON

[
  {
    "id": "s_21",
    "source": "initial",
    "choice_id": "present"
  },
  {
    "id": "s_24",
    "choice_id": "present"
  },
  {
    "id": "s_1535",
    "choice_id": "present"
  }
]

visit_date (datetime, optional)

The date of the visit to which the survey is associated.

expired_date (datetime, optional)

The expiration date of the survey, after which it can no longer be completed.

specialist (str, optional)

Speciality name.

Response

A survey identifier is returned in the response. This identifier will be used in other endpoints to perform actions on a specific survey.

Example:

JSON

{
  "id": "8ba7a7ad-996a-444e-b79b-77e373015617"
}

Listing surveys

To fetch a list of surveys, make a GET request to /api/v2/survey:

cURL

curl 'https:///api/v2/surveys' \
  -X 'GET'

The response will include a paginated list of surveys. The elements on a page can be limited using the limit parameter.

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:///api/v2/surveys?cursor=0",
  "first": "https:///api/v2/surveys?cursor=0",
  "prev": "null",
  "next": null,
  "last": "https:///api/v2/surveys?cursor=0",
  "items": [
    {
      "visit_date": null,
      "expired_date": null,
      "specialist": null,
      "id": "27bba1c9-37d1-4f91-8ab8-64f7a4d72f12",
      "status": "new",
      "last_modified_at": "2022-11-17T09:59:22.105669+00:00"
    },
    {
      "visit_date": null,
      "expired_date": null,
      "specialist": null,
      "id": "4aebc64a-e294-468c-9a40-fd234850e1c5",
      "status": "new",
      "last_modified_at": "2022-11-17T09:58:08.053865+00:00"
    },
    {
      "visit_date": null,
      "expired_date": null,
      "specialist": null,
      "id": "6d27f58e-8f50-4890-b9c7-2ec7bf6a6a49",
      "status": "completed",
      "last_modified_at": "2022-11-17T09:32:45.329011+00:00"
    }
  ]
}

Fields in response

status (str)

The survey can be in one of three statuses: new, pending, or completed.

last_modified_at (datetime)

Date and time the survey was last modified.

Deleting surveys

To delete a survey, send a DELETE request to /api/v2/surveys/{survey_id}. A successful response will return the status code HTTP 204.

Deleted surveys will be completely removed and no longer listed in the API.

Updating surveys

You can update the base information in a survey by making a PUT request to /api/v2/surveys/{survey_id}.

cURL

curl 'https:///api/v2/surveys/4aebc64a-e294-468c-9a40-fd234850e1c5' \
  -X 'PUT' \
  -H 'Content-Type: application/json' \
  -d '{
    "visit_date": "2022-11-19T14:43:55.757Z",
    "expired_date": "2022-11-19T14:43:55.757Z",
    "specialist": "Dermatologist"
  }'

Request parameters in body

visit_date (datetime, optional)

The date of the visit to which the survey is associated. Default value: null

expired_date (datetime, optional)

The expiration date of the survey, after which it can no longer be completed. Default value: null

specialist (str, optional)

Speciality name. Default value: null

Note: If the fields are not specified, empty values will be set.

Response

JSON

{
  "visit_date": "2022-11-19T14:43:55.757Z",
  "expired_date": "2022-11-19T14:43:55.757Z",
  "specialist": "Dermatologist"
}

Basics Navigating Question Flows