Invites and carers

A patient can share their record with a practitioner or with a carer (a FHIR RelatedPerson), and a practitioner can invite a patient into their care. Both send an email whose link opens the patient app at <patient app URL>/accept-invite?invite=<inviteId>&code=<code>.

The client methods and mutation hooks come from @ovok/core; @ovok/native adds carer sign-in and a hook that accepts the invite from the deep link.

Share a recordCopy Anchor Link

Use useShareRecord from @ovok/core while a patient is signed in. A carer gets only the Observation codes you name; a practitioner gets the whole record.

import { useShareRecord } from "@ovok/core";

const { mutate: shareRecord } = useShareRecord();

await shareRecord({
  recipient: "related-person",
  email: "carer@example.com",
  firstName: "Alex",
  lastName: "Doe",
  codes: ["8480-6", "8462-4"],
});

Use recipient: "practitioner" without codes to share with a practitioner. The answer is always { status: "sent" }, so it does not reveal whether the address has an account.

Accept an invite from its linkCopy Anchor Link

useAcceptInviteLink from @ovok/native reads invite and code from the link and picks the right route:

• accept.run(link): a signed-in patient accepts a practitioner's care invite; a signed-in carer accepts a record share.
• createCarerAccount.run(link, { email, password }): a new carer, signed out, sets a password. This creates their account, starts the share, and signs them in.

import { useAcceptInviteLink } from "@ovok/native";

const { accept, createCarerAccount } = useAcceptInviteLink({ tenantCode });

// `link` is the accept-invite URL your app's deep-link routing received.

// Signed in:
await accept.run(link);

// New carer, from a set-password form:
await createCarerAccount.run(link, { email, password });

The invite email does not tell the app whether the carer already has an account. Ask the carer to sign in or create a password, and use accept or createCarerAccount accordingly. A 409 with address_has_account from createCarerAccount means the address already has an account: sign in and call accept instead.

parseInviteLink(link) is exported for apps that route the link themselves. It throws when the link has no invite or code.

Sign in carersCopy Anchor Link

Set loginType="RelatedPerson" on SignIn.EmailForm (or type: "RelatedPerson" on useSignIn) with the tenant code. The project setting RELATED_PERSON_LOGIN_ENABLED must not be false. Carers reset a forgotten password with ResetPassword.Form and type="RelatedPerson".

Show and leave a carer's sharesCopy Anchor Link

A signed-in carer sees the shares patients gave them in received from usePatientSharing (@ovok/core 0.4.48 or later); it is empty for patients. Each entry has consentId, sharer, codes, startedAt and endsAt.

import { usePatientSharing, useRevokePatientSharing } from "@ovok/core";

const { data } = usePatientSharing();
const { mutate: leaveShare } = useRevokePatientSharing();

const received = data?.received ?? [];

await leaveShare(received[0].consentId);

Leaving a share ends it for both sides. A 404 means the share is not the carer's; a 409 means it already ended or changed meanwhile, so reload the list.

Deprecated invite methodsCopy Anchor Link

The @ovok/core methods invitePractitioner, invitePatient, acceptPractitionerInvite and acceptPatientInvite (and the hooks useInvitePractitioner and useInvitePatient) call routes that stop working on 1 December 2026. Use shareRecord, acceptRecordShare, inviteToCare and acceptCareInvite instead.