Skip to main content
Version: 3.0

Questionnaire Response

A questionnaire response is the set of answers a clinician or staff member records when they fill in a questionnaire for a patient. It turns a blank form — a triage screen, a vitals chart, an intake assessment — into a permanent, attributed piece of that patient's clinical record.

What it represents​

In Care's FHIR-aligned model, a questionnaire response maps to the QuestionnaireResponse resource. It captures:

  • The answers — what was entered for each question, kept both as the raw submission and as an extracted, query-friendly form
  • Who and what it is about — the patient, and the encounter it was recorded in when answered during a visit
  • Which form was answered — a link back to the questionnaire definition that was filled in
  • Provenance — who submitted it and when, maintained automatically by the platform

A questionnaire response is not the questionnaire itself. The questionnaire is the reusable template (the questions and their rules); the response is one patient's filled-in copy. Submitting the same form for ten patients produces ten responses against a single questionnaire.

How a response is captured​

Answers are not edited directly into a response record. They arrive through the submit flow: one submission carries the questionnaire being answered, the patient, the encounter if there is one, and the answer to every question. Care validates that whole payload against the questionnaire definition — required questions, allowed values, coded options — and only then writes the response. A submission that fails validation produces no response at all.

This is why a response is best thought of as a snapshot. It records what was answered at the moment of submission, attributed to the person who submitted it, against the patient and encounter in scope at that time.

Lifecycle​

A response is finalised the moment it is submitted; it has no draft state of its own.

completed → entered_in_error
  • completed — the response is finalised and part of the record (this is the default and normal state)
  • entered_in_error — the response was recorded by mistake; rather than deleting it, it is flagged so the history stays auditable

Because answers are not re-edited after submission, the only change applied to an existing response is marking it entered_in_error. Drafts, where they exist, live one level up in the form submission envelope (draft → submitted) before a response is written — see the technical reference.

How it connects​

  • Patient — every response belongs to a patient; it is governed by that patient's permission set
  • Encounter — when answered during a visit, the response is tied to that encounter, giving the answers a clinical context and timestamp
  • Questionnaire — the response points back to the questionnaire it answered; rendering the answers joins them against that definition so labels stay human-readable
  • Structured data — alongside the raw answers, a response can hold an extracted, query-friendly copy of those values. This is what lets a vitals form become real observations, or an allergy form become allergy records, rather than leaving the data locked inside a form

Permissions​

Questionnaire responses have no permission slug of their own. The read-only-plus-update viewset gates each action through the patient and encounter permission sets, choosing which permission to check based on whether the response is tied to an encounter.

PermissionDescriptionSystem Roles
can_view_questionnaire_responsesView the questionnaire responses on a patient when the response is not linked to an encounterVolunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist
can_view_clinical_dataView clinical data about a patient; satisfies viewing an encounter-linked response from the patient sideStaff, Doctor, Nurse, Admin, Facility Admin
can_read_encounter_clinical_dataRead an encounter's clinical data; alternatively satisfies viewing an encounter-linked response from the encounter sideAdmin, Doctor, Nurse, Facility Admin
can_submit_patient_questionnaireSubmit a questionnaire about a patient; required to update (correct) a response not linked to an encounterVolunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator
can_submit_encounter_questionnaireSubmit a questionnaire about a patient encounter; required to update (correct) an encounter-linked responseStaff, Doctor, Nurse, Admin, Facility Admin

Reads on an encounter-linked response are allowed if either can_view_clinical_data (patient) or can_read_encounter_clinical_data (encounter) is held; responses without an encounter fall back to can_view_questionnaire_responses. Updates are limited to marking a response entered_in_error within a short edit window and require the matching submit permission. Roles are granted through a user's organization, facility, or patient memberships, and permissions cascade down the organization tree — so access to a patient's responses follows from access to the patient.