# PATIENT_SHARING_ENABLED

Canonical page: https://docs.ovok.com/settings-and-features/settings/patient-sharing-enabled

Controls whether patients in the project can share selected readings with each other, and with [carers](/invitations/share-with-a-carer) 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` [#it-is-not-part-of-v1projectsettings]

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`](/errors/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 [#turn-it-on]

```bash
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](/settings-and-features/settings/default-practitioner-access-policy), 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 [#what-the-switch-controls]

Routes under `/v1/patient-sharing` are for signed-in patients. A [carer's](/authentication/carers) 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`](/invitations/share-with-a-carer) 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 [#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 [#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](/email-templates/map-templates) first, or the invitation is undone.

## Related [#related]

- [Invitations](/invitations), for the practitioner and care invitations that `practitionerSharingEnabled` switches on
- [Share readings with a carer](/invitations/share-with-a-carer), which `enabled` switches on
- [Settings and features](/settings-and-features)
- [PATIENT_INVITATION_ENABLED](/settings-and-features/settings/patient-invitation-enabled)
