Invitations
Bring people into an Ovok project with invitations, and choose between adding a project admin, sharing a patient's record with a practitioner or a carer, and inviting a patient into care.
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 |
| Let a clinician see my record | A patient | POST /v1/invites/record-share, recipient practitioner | Share a record with a practitioner |
| Let a carer see some of my readings | A patient | POST /v1/invites/record-share, recipient related-person | Share readings with a carer |
| Onboard a patient and see their record | A practitioner | POST /v1/invites/care | Invite a patient into care |
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.
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 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
Every invitation depends on project settings. The setup is the same idea as sign-in and registration: decide deliberately, and do not rely on defaults.
| Setting | Used by | When unset |
|---|---|---|
PRACTITIONER_INVITATION_ENABLED | Project admin; share with practitioner | On |
RELATED_PERSON_INVITATION_ENABLED | Share with carer, invite and accept | On |
PATIENT_INVITATION_ENABLED | Invite into care | On |
PRACTITIONER_APP_URL | Every link sent to a practitioner | Falls back; see the page |
PATIENT_APP_URL | Every link sent to a patient or a carer | Falls back; invitations answer 409 if nothing resolves |
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 | 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
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. |
Each email is rendered from a template that must be mapped 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 and the parameters each one carries.
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
- 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
- Invite a project admin
- Share a record with a practitioner
- Share readings with a carer, and Carers for what happens next
- Invite a patient into care
- Email templates, which choose what each invitation email says
Last updated on