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 -X 'POST' \
  'https:///api/v2/surveys' \
  -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_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:


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

Listing surveys

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



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

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:


{
  "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 -X 'PUT' \
 'https:///api/v2/surveys/4aebc64a-e294-468c-9a40-fd234850e1c5' \
  -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


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