Invitations
Registration lets people create their own account. Invitations let you, or a patient, bring someone in. Three routes do it, and they do different jobs: pick by who is calling and what should exist afterwards.
| I want to… | Who calls | Route | Page |
|---|---|---|---|
| Add a colleague to my project | A project admin | POST /v1/projects/me/members | Invite a team member |
| Let a clinician see my record | A patient | POST /v1/invites/practitioner | Share a record with a practitioner |
| Onboard a patient and see their record | A practitioner | POST /v1/invites/patient | Invite a patient |
The first creates a project membership. The other two create a data share: one patient's record becomes reachable by a practitioner. They are not interchangeable. An admin cannot use the two share routes to bring in a colleague, and a patient cannot use the members route at all.
How they differ
| Team member | Share with practitioner | Invite a patient | |
|---|---|---|---|
| Caller | Project admin | Patient | Practitioner with an AccessPolicy |
| Creates | A practitioner membership | A practitioner who holds the patient's record | A patient whose record the inviter holds |
| Answer | 200 with the new member | 202 { "status": "sent" }, always | 202 { "status": "sent" }, always |
| Existing address | Gets a membership, no email | Gets an offer to accept, by email | Gets an invite to accept, by email |
| Needs sharing switched on | No | Yes | Yes |
| Lasts | Until the member is removed | 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 | Team member; share with practitioner | On |
PATIENT_INVITATION_ENABLED | Invite a patient | On |
PRACTITIONER_APP_URL | Every link sent to a practitioner | Falls back; see the page |
PATIENT_APP_URL | Every link sent to a patient | 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 | Both share routes | Off |
Sharing is off by default. The two share routes refuse every call until an admin turns it 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. |
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 team members, PRACTITIONER_INVITED_BY_PATIENT and PRACTITIONER_PATIENT_SHARED for patient-to-practitioner shares, and PATIENT_INVITE and PATIENT_ASSIGNMENT_REQUEST for patient 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 |
|---|---|
POST /v1/projects/me/members | 500 Failed to send invite email. Please add the user manually if the issue persists. Nothing was created. |
POST /v1/invites/practitioner and /patient | 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 patient may hold at most 20 pending practitioner offers, and a practitioner at most 20 pending patient invitations. The next answers
429. - Every route here needs a bearer token, and the project comes from the token.
Next
- Invite a team member
- Share a record with a practitioner
- Invite a patient
- Email templates, which choose what each invitation email says