Patients

Use Patients to register every person once, find them by name, phone, patient number or UHID, keep consent-compliance details complete, and safely manage duplicates or restricted records.

Who can do this: Receptionists, Branch Managers, Practitioners and Super Admins with patient.read, patient.create and patient.update. Merging needs patient.merge. Restricted records need patient.readRestricted or assigned-practitioner access. Where: Patients (/app/patients), Patients → Register New Patient (/app/patients/register), patient details /app/patients/:patientId, DPDP Compliance (/app/patients/compliance).

Before you start

• Add branches before registering patients.
• Decide the duplicate policy: BLOCK prevents same-phone registration, WARN allows an audited override with a reason.
• For minors, collect guardian details and DPDP consent before saving.
• Use fictitious training data only. Never test with real patient information unless the clinic has authorised it.

Register a new patient

1. Open Patients and click Register New Patient. Result: Register Patient opens.
2. In Branch Selection, choose Select Branch.
3. In Personal Information, fill Full Name, Contact Number, Email if available, Date of Birth and Gender.
4. In Guardian Information, fill Guardian Name and Guardian Relation.
5. If the patient is under 18, tick I confirm parent/guardian consent has been obtained for collecting and processing this minor patient's personal data and for their treatment, as required under the DPDP Act.
6. Fill Address.
7. Add Primary Diagnosis, Secondary Diagnosis and Referred By if known.
8. Click Register Patient. Result: The toast says Patient registered successfully! and Achal returns to Patients. The backend assigns the UHID; the form cannot set it manually.

tip

Search before registering. Families may share one phone, so a matching phone does not always mean the same person, but you must check before creating another record.

Handle a BLOCK duplicate

1. If saving shows a duplicate card under Contact Number, read the existing patient's name, patient number and branch.
2. Click View existing patient. Result: The existing patient opens.
3. Use that record for appointment, bill, visit or document work.

Result: Under BLOCK, creating another active patient with the same phone is refused with PATIENT_PHONE_ALREADY_REGISTERED.

Handle a WARN duplicate

1. If Possible duplicate patient appears, review every candidate. Result: Candidates show masked details only: Initials, UHID, Birth year, Phone, and badges such as Same phone or Same name and date of birth.
2. Click Open existing if it is the same person.
3. If it is a different person, enter Why is this a different person?.
4. Click Create anyway. Result: The patient is registered and the duplicate override reason is saved in the audit log.

caution

If the panel says Another matching record exists that you cannot view. Ask an administrator before creating a new record., do not guess. Ask the owner or medical director to check restricted or other-branch records.

Search and open a patient

1. Open Patients.
2. Use Search patients by name, email, phone or patient number....
3. Click the patient row or card. Result: Patient details open at /app/patients/:patientId.
4. Review the UHID strip, Restricted record badge, clinical panels and personal information.

Edit a patient profile

1. Open the patient details page.
2. Click Edit.
3. Update editable details. In edit mode, Contact number is locked for existing patients.
4. If you deactivate a patient, clear Patient is active and can receive therapy sessions.
5. Click Update Patient. Result: The toast says Patient details updated successfully!

Complete the DPDP compliance queue

1. Open DPDP Compliance. Result: The page title is DPDP Compliance — Action Needed.
2. Review reasons: Missing Date of Birth or Minor — Guardian Consent Required.
3. Click Complete Profile.
4. Add the missing Date of Birth or guardian consent.
5. Click Update Patient. Result: The patient disappears from the compliance queue after the profile is complete.

Merge duplicate records

1. Open the surviving patient record, the one you want to keep.
2. In the identity strip, click Merge duplicate….
3. Search in Find the duplicate record by name, phone, patient number or UHID.
4. Click Search.
5. Click Select on the duplicate. Result: Records that will move to this patient shows counts for appointments, bills, packages, reports, clinical documents, encounters, vitals, problems, allergies, prescriptions, queue tokens and other linked records.
6. Enter Reason for merging.
7. Click Merge records. Result: The duplicate becomes a pointer that says This record was merged and Open surviving record.
8. If the merge is large and still In progress, click Resume merge from Merge history.
9. If the merge was wrong, click Undo merge, enter Reason for undoing the merge, then click Confirm undo. Result: Linked records moved by the merge are moved back when safe. Records changed since the merge may stay with the survivor.

caution

A restricted duplicate cannot be merged into a non-restricted survivor. The UI message is The duplicate record is restricted but this record is not. Restrict this record first, then merge.

Work with restricted records

1. Open the patient details page.
2. Look for the Restricted record badge in the identity strip and visit header.
3. Only the tenant owner or medical director with patient.readRestricted, or the assigned practitioner, should open it.
4. If access is denied, treat the missing record or Patient not found response as intentional privacy protection.

note

Restricted categories include VIP, psychiatry, HIV and employee health. Lists and searches hide restricted patients from users who cannot open them. Allowed and denied access are audited.

Troubleshooting

Problem / message	What it means	What to do
We could not load patients right now. Please try again.	The patient list failed.	Click Retry or reopen Patients.
Failed to fetch patients	The frontend could not load patient data.	Check connection and permissions, then retry.
Please correct the highlighted fields.	Registration validation failed on the browser.	Complete every highlighted field.
Please select the branch where this patient will be registered.	Select Branch is empty.	Choose a branch.
Enter the patient’s full name.	Full Name is empty.	Enter the patient's full name.
Enter a valid 10-digit mobile number.	New registration needs a 10-digit phone.	Enter the number without +91 or spaces.
Select the patient’s date of birth.	Date of Birth is empty.	Select the DOB.
Guardian consent is required for patients under 18.	Minor consent checkbox is not ticked.	Record guardian consent and tick the checkbox.
VALIDATION_FAILED Validation failed	Backend field validation failed.	Correct field messages returned by the API.
PATIENT_PHONE_ALREADY_REGISTERED	Duplicate policy BLOCK found an existing patient with the phone.	Open the existing record; do not create another.
PATIENT_POSSIBLE_DUPLICATE	Duplicate policy WARN found likely matches.	Open an existing record, or click Create anyway with a reason of 3 to 500 characters.
Enter a reason of 3–500 characters.	Duplicate override, merge or undo reason is too short or too long.	Type a clear reason.
RATE_LIMITED	Duplicate-check endpoint rate limit was hit.	Wait and search again.
UHID_ALLOCATION_FAILED	The backend could not safely reserve a UHID after retries.	Retry registration. If it repeats, contact support.
PATIENT_RESTRICTED or Patient not found	The patient is restricted or hidden from your role.	Ask the owner or assigned practitioner to open it.
PATIENT_MERGED	You tried to write to a merged-away record.	Click Open surviving record and continue there.
RESTRICTION_MISMATCH	A restricted duplicate was selected for a non-restricted survivor.	Restrict the survivor first, then merge.
MERGE_INCOMPLETE or The merge did not finish. It can be resumed from the merge history.	A merge stopped mid-run.	Click Resume merge in Merge history.
MERGE_NOT_RESUMABLE, MERGE_NOT_UNDOABLE, MERGE_UNDO_IN_PROGRESS	Another merge or undo lease is running.	Wait a few minutes and retry.
MERGE_UNDO_BLOCKED	Undo is blocked because another merge depends on it.	Undo the latest merge first.
You are offline. This form is saved on this device (encrypted). Submit again when you are back online — the UHID is assigned by the server.	Offline draft saved a new registration locally.	Keep the device signed in, reconnect, review the form and submit.

Related

• Owner role and restricted access
• Encounters
• Documents vault
• Workspaces & switching clinics
• Data import and export