PATIENT_SHARING_ENABLED
Let patients share chosen readings with another patient or a carer, how to turn it on, and why it is not in the project settings record.
Controls whether patients in the project can share selected readings with each other, and with carers by email. 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/settingsdoes not listPATIENT_SHARING_ENABLED.PUT /v1/project/settings/PATIENT_SHARING_ENABLEDanswers400withcodeUNKNOWN_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 and carer sharing on; false turns it off. |
practitionerSharingEnabled | boolean or null | A separate switch for the practitioner shares and care invitations under /v1/invites; carer shares answer to enabled. 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 practitioner shares and care invitations under /v1/invites 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. A carer's token answers 403 on all of them, so a carer cannot list or end shares yet.
| 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 |
POST /v1/invites/record-share with recipient related-person, and its /accept | 403 Sharing is not enabled for this project. |
GET /v1/patient-sharing/shares | Keeps working |
DELETE /v1/patient-sharing/shares/:consentId | Keeps working |
Turning sharing off stops new invitations and redemptions, carer invites and their acceptance included. 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
inviteIdandcodeonce 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/settingsfirst. -
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.
404for an unknown invitation or a wrong code,409if it was already used,410if it expired,400if 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.
-
Practitioner sharing sends four emails.
PRACTITIONER_INVITED_BY_PATIENT,PRACTITIONER_PATIENT_SHARED,PATIENT_INVITEandPATIENT_ASSIGNMENT_REQUESTmust be mapped first, or the invitation is undone.
Related
- Invitations, for the practitioner and care invitations that
practitionerSharingEnabledswitches on - Share readings with a carer, which
enabledswitches on - Settings and features
- PATIENT_INVITATION_ENABLED
Last updated on