Skip to main content

Restricted records FAQ

Use this page when a sensitive patient or clinical document is hidden, opens as not found, or needs owner approval.

Who can do this: owners with patient.readRestricted and patient.update; assigned practitioners for their own restricted patients; document authors or users with clinical.document.readRestricted for restricted documents. Where: patient details, clinical documents, and owner/admin access workflows.

Why does a patient show as ?not found??​

A restricted record may be hidden from users without access. Some patient-linked modules deliberately return not found instead of forbidden so the system does not reveal that a sensitive record exists.

  1. Check that you are in the correct workspace.
  2. Search by UHID or patient phone only if policy allows.
  3. Ask the owner to confirm whether the record is restricted.
  4. If you need access for treatment, request assignment or permission through clinic policy.

Patient-linked modules can return PATIENT_NOT_FOUND, Patient not found, Report not found or Document not found.

Which records can be restricted?​

Patients can be restricted as:

  • VIP
  • PSYCHIATRY
  • HIV
  • EMPLOYEE_HEALTH
  • OTHER

Some templates, such as psychiatry or psychology templates, can create restricted clinical documents by default.

Who can open a restricted patient?​

  • Owner or Super Admin with patient.readRestricted.
  • The assigned practitioner when their user id is in assignedTherapist, assignedPractitionerId, assignedDoctorId or assignedPractitionerIds.
  • Other staff cannot see the patient in lists or direct reads.

Every allowed or denied access is audited with ids only, no PHI.

Who can change restriction status?​

Changing restriction requires both patient.update and patient.readRestricted. The backend route is PUT /patients/:id/restriction.

Required fields are:

  1. restricted: true or false.
  2. category: one of VIP, PSYCHIATRY, HIV, EMPLOYEE_HEALTH or OTHER when restricted.
  3. reason: 3 to 500 characters.

The audit records restricted flag, category, who changed it and reason length. The free-text reason is not logged.

How should an owner mark a patient restricted?​

A visible frontend button for this route was not present in the files reviewed. If your deployment has an owner workflow, use the label shown there; otherwise raise the change through support/admin.

  1. Confirm the patient identity using UHID and phone.
  2. Confirm the category and reason under clinic policy.
  3. Apply the restriction through the approved owner/admin workflow.
  4. Reopen the patient list and confirm the red Restricted badge appears for users who may see it.
  5. Tell staff that non-authorised users may now see Patient not found.

How should an owner unmark a restriction?​

Do not remove restrictions just to make search easier.

  1. Review the access and restriction audit trail.
  2. Confirm policy allows removal.
  3. Set restricted to false through the approved owner/admin workflow.
  4. Keep a reason of 3 to 500 characters.
  5. Confirm normal staff visibility only if role and branch rules allow it.

Why can I see the patient but not a document?​

Clinical documents also have document-level restriction. Restricted documents are invisible with 404-style behaviour to everyone except the author and holders of clinical.document.readRestricted.

  1. Ask the document author to confirm whether the document itself is restricted.
  2. Ask the owner whether your role has clinical.document.readRestricted.
  3. If you only need patient-level access, do not assume that grants document-level access.

The generated role matrix deliberately does not grant clinical.document.readRestricted to standard role bundles.

How do I request access safely?​

  1. Use the clinic's internal approval path or Help & Support (/app/support).
  2. Send only the UHID or document number if policy permits.
  3. State why access is needed for care or administration.
  4. Wait for the owner to assign you or grant the correct permission.
  5. Do not ask another staff member to screenshot the record.

What is audited for restricted records?​

The system audits:

  1. Restricted list exposure as PATIENT_RESTRICTED_LIST_ACCESS.
  2. Allowed direct access as PATIENT_RESTRICTED_ACCESS.
  3. Denied access as PATIENT_RESTRICTED_ACCESS_DENIED.
  4. Restriction changes as PATIENT_RESTRICTION_CHANGED.
  5. Care-team changes on restricted patients as PATIENT_CARE_TEAM_CHANGED.

Audit metadata uses ids and counts. It does not store the free-text restriction reason.

Still stuck?​

Open Help & Support (/app/support) and send the UHID or document number only if clinic policy allows it, the time, the screen, and the exact message. Do not share diagnoses, patient names, screenshots with PHI, or restricted-record details in chat.