PATIENT_SHARING_ENABLED

Controls whether patients in the project can share selected readings with each other. A patient creates a short-lived invitation for the observation codes they choose; another patient redeems it and can then read those readings until the share is ended.

Type	Boolean setting, managed through its own endpoint
Change with	PUT /v1/patient-sharing/settings
Read with	GET /v1/patient-sharing/settings
Who can change it	Project admin
When unset	Off
Set on new projects	Not set by any project-creation route
Inherited	No. A child project reads only its own value.

It is not part of /v1/project/settings

Every other setting on these pages is read from GET /v1/project/settings and changed with PUT /v1/project/settings/:key. This one is not.

• GET /v1/project/settings does not list PATIENT_SHARING_ENABLED.
• PUT /v1/project/settings/PATIENT_SHARING_ENABLED answers 400 with code UNKNOWN_SETTING.
• The patient-sharing endpoints below are admin-only. Reading the project settings needs only a practitioner session, so a dashboard that shows the settings record cannot show or change this switch.

Turn it on

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/patient-sharing/settings' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"enabled":true}'

Body field	Type	Description
enabled	boolean, required	true turns patient-to-patient sharing on; false turns it off.
practitionerSharingEnabled	boolean or null	A separate switch for the patient and practitioner invitation routes under /v1/invites. Leave it out, or send null, to keep its current value. Leave it off unless you need it: with it on, a signed-in patient can create a practitioner account, with your default practitioner AccessPolicy, for a new address.

Response field	Example	Meaning
enabled	true	Whether patient-to-patient sharing is on.
accessPolicyId	"b7e1c2d3-…" or null	The id of the read-only AccessPolicy every share points at; null until sharing has been turned on once.
practitionerSharingEnabled	false	Whether the /v1/invites routes are on.

Turning sharing on creates the read-only sharing AccessPolicy, or brings an existing one up to date, in the same write as the setting. Turning it off writes only enabled: false and keeps the policy.

Status	Meaning
403	The caller is not a project admin.
404	The project does not exist.
409	The project changed during the write. Read the settings again and retry.
422	The body fails validation, for example enabled is missing or not a boolean.

What the switch controls

Routes under /v1/patient-sharing are for signed-in patients.

Route	When sharing is off
POST /v1/patient-sharing/invites (create an invitation)	403 Sharing is not enabled for this project.
POST /v1/patient-sharing/invites/redeem	403
GET /v1/patient-sharing/shares	Keeps working
DELETE /v1/patient-sharing/shares/:consentId	Keeps working

Turning sharing off stops new invitations and redemptions. Existing shares stay in force until they are ended, and patients can still list and end them.

Limits worth designing around

Limit	Value
Invitation lifetime	15 minutes
Open invitations per patient	10. The eleventh answers 429 Too many open invites; wait for some to expire.
Codes per invitation	1 to 100, each up to 64 letters, digits, . or -
endsAt	Must be null. A date answers 400 Shares that end on a date are not available yet; share until revoked.
code when redeeming	16 to 128 characters

Gotchas

• Nothing is emailed. A patient-to-patient invitation needs no app URL and sends no message. The creating patient receives inviteId and code once and must pass them to the other patient out of band. Only a hash of the code is stored, so a lost code cannot be recovered; create a new invitation.
• Off by default, and there is no project-settings read for it. If sharing appears broken, call GET /v1/patient-sharing/settings first.
• Admin only, strictly. A session that holds the System Owner access policy but is not a project admin is refused.
• Redeeming has several distinct failures. 404 for an unknown invitation or a wrong code, 409 if it was already used, 410 if it expired, 400 if the caller made the invitation or their account has no access policy.
• Sharing is read-only. The recipient can read and search the shared observation codes, and sees the sharer's patient record with contact details and identifiers hidden.

Related

• Invitations, for the patient and practitioner invitations that practitionerSharingEnabled switches on
• Settings and features
• PATIENT_INVITATION_ENABLED