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 callsRoutePage
Add an admin to my projectA project adminThe Console's Members pageInvite a project admin
Let a clinician see my recordA patientPOST /v1/invites/record-share, recipient practitionerShare a record with a practitioner
Let a carer see some of my readingsA patientPOST /v1/invites/record-share, recipient related-personShare readings with a carer
Onboard a patient and see their recordA practitionerPOST /v1/invites/careInvite 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 adminShare with practitionerShare with carerInvite into care
CallerProject adminPatientPatientPractitioner with an AccessPolicy
CreatesAn admin membershipA practitioner who holds the patient's recordA carer who reads the chosen codesA patient whose record the inviter holds
Recipient readsThe whole project, as an adminThe whole recordChosen Observation codes and the patient's nameThe whole record
AnswerThe Console shows the new admin202 { "status": "sent" }, always202 { "status": "sent" }, always202 { "status": "sent" }, always
New addressAccount and set-password emailAccount and set-password emailAccept link; the account is made on acceptAccount and set-password email
Existing addressGets a membership, no emailGets an offer to accept, by emailGets an invite to accept, by emailGets an invite to accept, by email
Needs sharing switched onNoYes, practitionerSharingEnabledYes, enabledYes, practitionerSharingEnabled
LastsUntil the admin is removedUntil the patient ends the shareUntil the patient ends the shareUntil 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.

SettingUsed byWhen unset
PRACTITIONER_INVITATION_ENABLEDProject admin; share with practitionerOn
RELATED_PERSON_INVITATION_ENABLEDShare with carer, invite and acceptOn
PATIENT_INVITATION_ENABLEDInvite into careOn
PRACTITIONER_APP_URLEvery link sent to a practitionerFalls back; see the page
PATIENT_APP_URLEvery link sent to a patient or a carerFalls back; invitations answer 409 if nothing resolves
DEFAULT_PRACTITIONER_ACCESS_POLICYA new practitioner's policyRoutes that need it answer 409
Default patient AccessPolicyA new patient's policyRoutes that need it answer 409
practitionerSharingEnabled, set with PUT /v1/patient-sharing/settingsShare with practitioner; invite into careOff
enabled, set with the same routeShare with carerOff

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.

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

LinkShapeYour 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:

RouteWhat you see
The Console's Members pageThe invite fails with an error. Nothing was created.
POST /v1/invites/record-share and /careStill 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

  1. Invite a project admin
  2. Share a record with a practitioner
  3. Share readings with a carer, and Carers for what happens next
  4. Invite a patient into care
  5. Email templates, which choose what each invitation email says

Last updated on

On this page