# Share a record with a practitioner

Canonical page: https://docs.ovok.com/invitations/share-with-practitioner

A signed-in **patient** shares their whole record with a practitioner, by email. If the address is new, Ovok creates a practitioner account that already holds the share. If it belongs to a practitioner of the project, that practitioner receives an offer to accept.

The same route [shares chosen readings with a carer](/invitations/share-with-a-carer) when `recipient` is `related-person`.

| Step | Method | Path | Who |
| --- | --- | --- | --- |
| 1. Invite | `POST` | `/v1/invites/record-share` with `"recipient": "practitioner"` | A patient |
| 2. Accept (existing practitioners only) | `POST` | `/v1/invites/record-share/accept` | The invited practitioner |

## What the project needs [#what-the-project-needs]

Each row must hold before the address is looked up.

| Requirement | Detail |
| --- | --- |
| Practitioner sharing on | `practitionerSharingEnabled`, set with [`PUT /v1/patient-sharing/settings`](/settings-and-features/settings/patient-sharing-enabled). **Off by default.** |
| Practitioner invitations on | [`PRACTITIONER_INVITATION_ENABLED`](/settings-and-features/settings/practitioner-invitation-enabled) must not be `false`. |
| A practitioner app URL | [`PRACTITIONER_APP_URL`](/settings-and-features/settings/practitioner-app-url). The request's `Origin` is never used here, because the caller is a patient. |
| A default practitioner AccessPolicy | [`DEFAULT_PRACTITIONER_ACCESS_POLICY`](/settings-and-features/settings/default-practitioner-access-policy), or the older [`CLINICIAN_INVITE_ACCESS_POLICY`](/settings-and-features/settings/default-practitioner-access-policy). |
| Fewer than 20 pending offers | Per patient. |
| Two email templates mapped | `PRACTITIONER_INVITED_BY_PATIENT` and `PRACTITIONER_PATIENT_SHARED`, [mapped](/email-templates/map-templates) with a provider that is `ready`. |

## Step 1: Invite [#step-1-invite]

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/record-share' \
  --header "Authorization: Bearer ${PATIENT_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"recipient":"practitioner","email":"dr.smith@example.com","firstName":"Alex","lastName":"Smith"}'
```

| Body field | Required | Description |
| --- | --- | --- |
| `recipient` | Yes | `practitioner`. |
| `email` | Yes | A valid address, up to 254 characters. Ovok lowercases it. |
| `firstName` | Yes | 1 to 200 characters. Used when a new account is created. |
| `lastName` | Yes | 1 to 200 characters. |

The answer is always `202 Accepted` with `{ "status": "sent" }`, whatever the address turned out to be, so it cannot reveal which emails have accounts. Tell the patient "if they have an account, they will be emailed". If the email cannot be sent, everything the invitation wrote is undone and the answer is still `202`: [map the two templates](/email-templates/set-up-email) first.

### What happens, by address [#what-happens-by-address]

| The address… | What Ovok does |
| --- | --- |
| Has no account | Creates a practitioner of the project with the default practitioner AccessPolicy and the patient's share, in one write, and emails a set-password link (`PRACTITIONER_INVITED_BY_PATIENT`). |
| Belongs to exactly one active practitioner of the project | Creates a pending offer and emails an accept link (`PRACTITIONER_PATIENT_SHARED`), valid for 7 days and usable once. The share starts only when step 2 succeeds. |
| Already holds this patient's share | Sends nothing, unless their account still has no password, in which case the set-password email goes out again. |
| Anything else | Writes and sends nothing: for example an account that is not a practitioner of this project, or a practitioner with full project access. A share would narrow full access, so accepting it fails with [`practitioner_without_access_policy`](/errors/practitioner-without-access-policy); give people who should receive shares a limited AccessPolicy. |

A new practitioner's set-password link works for 7 days; after that, invite the person again. See [the shared invitation-link rule](/invitations#limits-and-shared-behaviour). Your practitioner app must serve the `/accept-invite` and `/setpassword` paths the emails point at.

## Step 2: Accept [#step-2-accept]

The practitioner opens the link `<practitioner app URL>/accept-invite?invite=<inviteId>&code=<code>` in your app, signs in, and your app posts both values:

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/record-share/accept' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"inviteId":"8c1e5a52-6f0b-4d9e-9a41-0b2f7c3d9e10","code":"<code from the link>"}'
```

| Body field | Description |
| --- | --- |
| `inviteId` | The `invite` value from the link. A UUID. |
| `code` | The `code` value from the link, 16 to 128 characters. |
| `password` | Optional. Send `null` or leave it out; it is only for a [new carer](/invitations/share-with-a-carer#a-new-carer-choose-a-password-no-token). |

On success the answer is `200` with the share:

| Field | Example | Meaning |
| --- | --- | --- |
| `consentId` | `…` | Id used to end the share later. |
| `sharer.patientId` | `…` | Patient whose record is shared. |
| `sharer.name` | `Jane Doe` | Patient's display name. |
| `practitioner.practitionerId` | `…` | Practitioner receiving access. |
| `practitioner.name` | `Dr. Alex Smith` | Practitioner's display name. |
| `startedAt` | `2026-10-06T08:15:00.000Z` | Time the share began. |
| `endsAt` | `null` | No scheduled end time. |

The share covers the whole record, with no list of codes to choose, and lasts until the patient ends it with `DELETE /v1/patient-sharing/shares/:consentId`. The practitioner can read, search, create and update Observations, Communications, DocumentReferences, QuestionnaireResponses, ServiceRequests, Tasks and Appointments; read CommunicationRequests, Goals, CarePlans, Flags, EpisodeOfCare and DeviceUseStatements; and read, search and update the Patient. Nothing can be deleted. The change applies on the practitioner's next request.

## What can go wrong [#what-can-go-wrong]

**Invite**

| Status | Message or `error` | Cause |
| --- | --- | --- |
| `401` | | The token is missing or invalid. |
| `403` | `Only patients can invite practitioners.` | The caller is not a patient. |
| `403` | | Practitioner sharing is off, or [`PRACTITIONER_INVITATION_ENABLED`](/settings-and-features/settings/practitioner-invitation-enabled) is `false`. |
| `409` | `code` [`app_url_not_configured`](/errors/app-url-not-configured) | No practitioner app URL. Fix the configuration; retrying will not help. |
| `409` | `error` [`invitation_not_configured`](/errors/invitation-not-configured) | No default practitioner AccessPolicy. |
| `409` | | Another write holds the address, or the records kept changing. Retry. |
| `429` | | The patient already has 20 pending offers. |
| `422` | A list of `path` and `message` | A field is missing or invalid, or `recipient` is neither `practitioner` nor `related-person`. |

**Accept**

| Status | Message or `error` | Cause |
| --- | --- | --- |
| `401` | `Sign in as the practitioner this offer is for.` | No token was sent. Also, with no message, when the token is invalid. |
| `403` | `Practitioner sharing is not enabled for this project.` | Sharing is off, the usual cause when every call answers `403`. Checked before the caller's role. |
| `403` | | [`PRACTITIONER_INVITATION_ENABLED`](/settings-and-features/settings/practitioner-invitation-enabled) is `false`, or the caller is not a practitioner. |
| `404` | | No live offer has this `inviteId`, the `code` does not match, the offer names another practitioner, or the caller has no practitioner membership in the project. |
| `409` | | The offer was already used, the patient is no longer a member, or the records kept changing. |
| `409` | `error` [`practitioner_without_access_policy`](/errors/practitioner-without-access-policy) | The practitioner has full project access, which a share would narrow. |
| `410` | | The offer expired. |
| `422` | A list of `path` and `message` | `inviteId` is not a UUID, or `code` is shorter than 16 characters. |

## Deprecated routes [#deprecated-routes]

Until 1 December 2026 the same flow also answers on `POST /v1/invites/practitioner` (no `recipient` field) and `POST /v1/invites/practitioner/accept`, with the same behaviour and status codes. Both are deprecated; see [Deprecated routes](/production/deprecated-routes#invitations-deprecated-22-october-2026).

## Related [#related]

- [Email templates](/email-templates)
- [Invitations](/invitations)
- [Invite a patient into care](/invitations/invite-a-patient), the same share started by the practitioner
- [Share readings with a carer](/invitations/share-with-a-carer)
- [PATIENT_SHARING_ENABLED](/settings-and-features/settings/patient-sharing-enabled)
