Share a record with a practitioner
Let a signed-in patient share their whole record with a practitioner by email, and how the practitioner accepts it.
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 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
Each row must hold before the address is looked up.
| Requirement | Detail |
|---|---|
| Practitioner sharing on | practitionerSharingEnabled, set with PUT /v1/patient-sharing/settings. Off by default. |
| Practitioner invitations on | PRACTITIONER_INVITATION_ENABLED must not be false. |
| A practitioner app URL | 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, or the older CLINICIAN_INVITE_ACCESS_POLICY. |
| Fewer than 20 pending offers | Per patient. |
| Two email templates mapped | PRACTITIONER_INVITED_BY_PATIENT and PRACTITIONER_PATIENT_SHARED, mapped with a provider that is ready. |
Step 1: Invite
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 first.
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; 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. Your practitioner app must serve the /accept-invite and /setpassword paths the emails point at.
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:
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. |
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
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 is false. | |
409 | code app_url_not_configured | No practitioner app URL. Fix the configuration; retrying will not help. |
409 | error 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 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 | 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
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.
Related
- Email templates
- Invitations
- Invite a patient into care, the same share started by the practitioner
- Share readings with a carer
- PATIENT_SHARING_ENABLED
Last updated on