# Invitations

Canonical page: https://docs.ovok.com/invitations

Registration lets people create their own account. **Invitations** let you, or a patient, bring someone in. Each route is named for its purpose: pick by who is calling and what should exist afterwards.

| I want to… | Who calls | Route | Page |
| --- | --- | --- | --- |
| Add an admin to my project | A project admin | The Console's **Members** page | [Invite a project admin](/invitations/team-members) |
| Let a clinician see my record | A patient | `POST /v1/invites/record-share`, `recipient` `practitioner` | [Share a record with a practitioner](/invitations/share-with-practitioner) |
| Let a carer see some of my readings | A patient | `POST /v1/invites/record-share`, `recipient` `related-person` | [Share readings with a carer](/invitations/share-with-a-carer) |
| Onboard a patient and see their record | A practitioner | `POST /v1/invites/care` | [Invite a patient into care](/invitations/invite-a-patient) |

The first creates a **project membership**. The others create a **data share**: one patient's record, or chosen readings from it, becomes reachable by someone else. They are not interchangeable. An admin cannot use the share routes to bring in a colleague, and a patient cannot use the members route at all.

Each share invite is accepted at the matching route: `POST /v1/invites/record-share/accept` or `POST /v1/invites/care/accept`. The older `/v1/invites/practitioner` and `/v1/invites/patient` routes still answer until 1 December 2026; see [Deprecated routes](/production/deprecated-routes#invitations-deprecated-22-october-2026).

## How they differ [#how-they-differ]

| | Project admin | Share with practitioner | Share with carer | Invite into care |
| --- | --- | --- | --- | --- |
| Caller | Project admin | Patient | Patient | Practitioner with an AccessPolicy |
| Creates | An admin membership | A practitioner who holds the patient's record | A [carer](/authentication/carers) who reads the chosen codes | A patient whose record the inviter holds |
| Recipient reads | The whole project, as an admin | The whole record | Chosen Observation codes and the patient's name | The whole record |
| Answer | The Console shows the new admin | `202` `{ "status": "sent" }`, always | `202` `{ "status": "sent" }`, always | `202` `{ "status": "sent" }`, always |
| New address | Account and set-password email | Account and set-password email | Accept link; the account is made on accept | Account and set-password email |
| Existing address | Gets a membership, **no email** | Gets an offer to accept, by email | Gets an invite to accept, by email | Gets an invite to accept, by email |
| Needs sharing switched on | No | **Yes**, `practitionerSharingEnabled` | **Yes**, `enabled` | **Yes**, `practitionerSharingEnabled` |
| Lasts | Until the admin is removed | Until the patient ends the share | Until the patient ends the share | Until the patient ends the share |

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

Every invitation depends on project settings. The setup is the same idea as [sign-in and registration](/authentication/project-setup): decide deliberately, and do not rely on defaults.

| Setting | Used by | When unset |
| --- | --- | --- |
| [`PRACTITIONER_INVITATION_ENABLED`](/settings-and-features/settings/practitioner-invitation-enabled) | Project admin; share with practitioner | On |
| [`RELATED_PERSON_INVITATION_ENABLED`](/settings-and-features/settings/related-person-invitation-enabled) | Share with carer, invite and accept | On |
| [`PATIENT_INVITATION_ENABLED`](/settings-and-features/settings/patient-invitation-enabled) | Invite into care | On |
| [`PRACTITIONER_APP_URL`](/settings-and-features/settings/practitioner-app-url) | Every link sent to a practitioner | Falls back; see the page |
| [`PATIENT_APP_URL`](/settings-and-features/settings/patient-app-url) | Every link sent to a patient or a carer | Falls back; invitations answer `409` if nothing resolves |
| [`DEFAULT_PRACTITIONER_ACCESS_POLICY`](/settings-and-features/settings/default-practitioner-access-policy) | A new practitioner's policy | Routes that need it answer `409` |
| Default patient AccessPolicy | A new patient's policy | Routes that need it answer `409` |
| `practitionerSharingEnabled`, set with [`PUT /v1/patient-sharing/settings`](/settings-and-features/settings/patient-sharing-enabled) | Share with practitioner; invite into care | **Off** |
| `enabled`, set with the same route | Share with carer | **Off** |

Sharing is off by default. The share routes refuse every call until an admin turns the matching switch on.

> **Before you turn sharing on.** With it on, a signed-in patient can create a practitioner account for a new address, and a practitioner can create a patient account. Each new practitioner receives your default practitioner AccessPolicy, so make sure it gives a new practitioner nothing a patient should not hand out. Do not turn it on in a project whose practitioners use the Ovok care dashboard: a practitioner who only holds shared patients could see project-wide data there.

## Emails and the links in them [#emails-and-the-links-in-them]

An invitation is an email with a link, and the link points at **your** app, built on the matching app URL.

| Link | Shape | Your app must |
| --- | --- | --- |
| Set a password | `<app URL>/setpassword/<id>/<secret>` | Serve a page where the person chooses a password, then send them to sign in. |
| Accept an invitation | `<app URL>/accept-invite?invite=<inviteId>&code=<code>` | Sign the person in, then post `inviteId` and `code` to the matching `accept` route. A new carer is not signed in: they choose a password instead; see [which form to show](/invitations/share-with-a-carer#which-form-to-show). |

Each email is rendered from a template that must be [mapped](/email-templates/map-templates) to one of yours first, and whose provider must be `ready`: `INVITE_TO_PROJECT` for project admins, `PRACTITIONER_INVITED_BY_PATIENT` and `PRACTITIONER_PATIENT_SHARED` for patient-to-practitioner shares, `RELATED_PERSON_INVITED` and `RELATED_PERSON_RECORD_SHARED` for carer shares, and `PATIENT_INVITE` and `PATIENT_ASSIGNMENT_REQUEST` for care invitations. See [Email templates](/email-templates) and [the parameters each one carries](/email-templates/template-catalogue#parameters).

**If an invitation's email cannot be sent, the invitation is undone**, but the routes report it differently:

| Route | What you see |
| --- | --- |
| The Console's **Members** page | The invite fails with an error. Nothing was created. |
| `POST /v1/invites/record-share` and `/care` | Still `202`. Nothing was created and nothing was sent. |

## Limits and shared behaviour [#limits-and-shared-behaviour]

- A share invitation is single use and expires 7 days after it is sent.
- A set-password link from an invitation works for 7 days after it is sent. After that the set-password routes answer `410`; invite the person again and the new link replaces the old one.
- A patient may hold at most 20 pending practitioner offers and 20 pending carer invites, and a practitioner at most 20 pending care invitations. The next answers `429`.
- Every route here needs a bearer token, and the project comes from the token. The one exception is a new carer accepting an invite, who has no account yet.

## Next [#next]

1. [Invite a project admin](/invitations/team-members)
2. [Share a record with a practitioner](/invitations/share-with-practitioner)
3. [Share readings with a carer](/invitations/share-with-a-carer), and [Carers](/authentication/carers) for what happens next
4. [Invite a patient into care](/invitations/invite-a-patient)
5. [Email templates](/email-templates), which choose what each invitation email says
