ADR 006 — Patients and Kulcare sends use only a verified facility email and phone
Status: Accepted. The build is not merged yet.
Date: 2026-10-12
Context tags: identity, facility, verification, notifications, connect, cms
Plan: docs/plans/2026-10-12-feat-facility-contact-verification-plan.md on branch
feat/cpp2-facility-contact-verify. The plan has the data model, the API contract, the list of every read
to change, and the tests. This page records the decisions only.
Context
A facility has one contact email (identity.facilities.email) and a list of public phone numbers on each
location (identity.facility_locations.phone_numbers). Any member with manage_facilities can type them, and
a platform admin can type them in the admin app. Kulcare never checks that the facility owns them. But Kulcare
shows them to patients in search, the public listing and the patient app. Kulcare also puts them in what it
sends: SMS, WhatsApp, the prescription email, the invoice email and the patient data export. A typo or a false
value sends patients, and patient data, to the wrong person.
Decision
The facility must verify its email and each public phone number before Kulcare shows it to patients or sends facility mail or SMS to it. The rule applies to every role and every path that edits a facility.
| # | Question | Decision |
|---|---|---|
| Q1 | Old facility emails and phones | No backfill. Old values start unverified. A switch, FACILITY_CONTACT_VERIFICATION_ENFORCED, turns the gate on. It is on in development, test and staging, and off in production until a coverage report shows enough verified facilities. Before the switch goes on, a CMS banner and a one-time email tell the facility editors. |
| Q2 | A value that is the same as the editor's own sign-in email or phone | The save marks it verified (method account_match), when the editor's own email or phone is verified. A platform admin's own email or phone never verifies a facility contact. |
| Q3 | Landlines, which cannot get an SMS | SMS codes, plus a platform-admin action "verified by call" for a phone. The admin calls the number and records the result. The action records the admin and the time. It never applies to an email. A voice-call code is a separate follow-up. |
| Q4 | The "Hidden from patients" setting for phone numbers | The gate obeys it. When it is off, patients get no facility phone, verified or not. |
| Q5 | Documents | The gate applies to what Kulcare sends or shows to patients: SMS, WhatsApp, email, the patient app, the public listing, search and the patient data export. A document that facility staff print or download themselves keeps the stored contact. |
| Q6 | Can a platform admin verify? | A platform admin can send the code to the facility phone or email. Only a member of the practice who can edit the facility can enter the code, and the admin never sees it. The only verification that an admin completes alone is "verified by call" (Q3). |
Rules that follow from these decisions:
- Kulcare keeps the verified state on the facility, with the value it verified. A change of the value removes the verification. When an editor removes a number and adds it again, the facility must verify it again.
- One read model gives the public email and the public phones. Every read that patients see, and every Kulcare send, uses it.
- In Connect profile completeness, the needed facility phone item is done only when at least one phone is verified (by code, account match or call). The recommended facility email item is done only when the email is verified. Each item links to the control that verifies it.
Consequences
Positive
- Patients, and patient data, reach only a contact that the facility proved it owns.
- One read model replaces many direct reads of the stored values, so a new feature cannot skip the gate by mistake.
Negative
- Until a facility verifies, patients see no facility phone or email once the switch is on. The banner, the email and the completeness items push editors to verify before that.
- A facility with only a landline needs a platform admin to call it.
- Print and download paths still show the stored values, so a document printed by staff can show a contact that patients do not see.
Related
- Profile completeness
- Verify a phone or email after an admin change: the same rule for a user's own sign-in phone and email.