Settings

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.

TypeBoolean setting, managed through its own endpoint
Change withPUT /v1/patient-sharing/settings
Read withGET /v1/patient-sharing/settings
Who can change itProject admin
When unsetOff
Set on new projectsNot set by any project-creation route
InheritedNo. 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 fieldTypeDescription
enabledboolean, requiredtrue turns patient-to-patient and carer sharing on; false turns it off.
practitionerSharingEnabledboolean or nullA 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 fieldExampleMeaning
enabledtrueWhether patient-to-patient sharing is on.
accessPolicyId"b7e1c2d3-…" or nullThe id of the read-only AccessPolicy every share points at; null until sharing has been turned on once.
practitionerSharingEnabledfalseWhether 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.

StatusMeaning
403The caller is not a project admin.
404The project does not exist.
409The project changed during the write. Read the settings again and retry.
422The 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.

RouteWhen sharing is off
POST /v1/patient-sharing/invites (create an invitation)403 Sharing is not enabled for this project.
POST /v1/patient-sharing/invites/redeem403
POST /v1/invites/record-share with recipient related-person, and its /accept403 Sharing is not enabled for this project.
GET /v1/patient-sharing/sharesKeeps working
DELETE /v1/patient-sharing/shares/:consentIdKeeps 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

LimitValue
Invitation lifetime15 minutes
Open invitations per patient10. The eleventh answers 429 Too many open invites; wait for some to expire.
Codes per invitation1 to 100, each up to 64 letters, digits, . or -
endsAtMust be null. A date answers 400 Shares that end on a date are not available yet; share until revoked.
code when redeeming16 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.

  • Practitioner sharing sends four emails. PRACTITIONER_INVITED_BY_PATIENT, PRACTITIONER_PATIENT_SHARED, PATIENT_INVITE and PATIENT_ASSIGNMENT_REQUEST must be mapped first, or the invitation is undone.

Last updated on

On this page