# Invites and carers

Canonical page: https://docs.ovok.com/native-sdk/guide/how-to/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 record [#share-a-record]

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.

```tsx
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 link [#accept-an-invite-from-its-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.

```tsx
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 carers [#sign-in-carers]

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 shares [#show-and-leave-a-carers-shares]

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`.

```tsx
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 methods [#deprecated-invite-methods]

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.