Invite a patient

A signed-in practitioner invites a patient by email. If the address is new, Ovok creates a patient account whose record is already shared with the inviter. If it belongs to a patient of the project, that patient receives an invitation to accept.

Step	Method	Path	Who
1. Invite	POST	/v1/invites/patient	A practitioner
2. Accept (existing patients only)	POST	/v1/invites/patient/accept	The invited patient

What the project needs

Every row must hold before the address is looked up.

Requirement	Detail
Practitioner sharing on	practitionerSharingEnabled, set with PUT /v1/patient-sharing/settings. Off by default.
Patient invitations on	PATIENT_INVITATION_ENABLED must not be false.
A patient app URL	PATIENT_APP_URL. The request's Origin is never used here.
A default patient AccessPolicy	defaultPatientAccessPolicy on the project; see set up your project.
An inviter with an AccessPolicy	The practitioner's membership must have one. A member with full project access is refused.
Fewer than 20 pending invitations	Per practitioner.
Two email templates mapped	PATIENT_INVITE and PATIENT_ASSIGNMENT_REQUEST, mapped with a provider that is ready.

Step 1: Invite

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/patient' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"email":"jane@example.com","firstName":"Jane","lastName":"Doe"}'

Body field	Required	Description
email	Yes	A valid address, up to 254 characters. Ovok lowercases it.
firstName	Yes	1 to 200 characters. Used when a new account is created.
lastName	Yes	1 to 200 characters.

The answer is always 202 Accepted, with the same response for every address outcome below:

Field	Value
status	sent

What happens, by address

The address…	What Ovok does
Has no account	Creates a patient of the project with the default patient AccessPolicy and shares the record with the inviter, in one write, and emails a set-password link (PATIENT_INVITE).
Belongs to exactly one active patient of the project	Creates a pending invitation and emails an accept link (PATIENT_ASSIGNMENT_REQUEST), valid for 7 days. The share starts only when step 2 succeeds.
Already shares their record with the inviter	Sends nothing, unless their account still has no password, in which case the set-password email goes out again.
Anything else	Writes and sends nothing. For example an account that is not a patient of this project.

Step 2: Accept

The patient opens <patient app URL>/accept-invite?invite=<inviteId>&code=<code> in your app, signs in, and your app posts both values:

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/patient/accept' \
  --header "Authorization: Bearer ${PATIENT_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"inviteId":"8c1e5a52-6f0b-4d9e-9a41-0b2f7c3d9e10","code":"<code from the link>"}'

Body field	Description
inviteId	The invite value from the link. A UUID.
code	The code value from the link, 16 to 128 characters.

On success the answer is 200 with the share (the same shape as sharing with a practitioner). The practitioner then holds the patient's whole record, with the same access described there: no deletes, and the Patient can be read, searched and updated.

What can go wrong

Invite

Status	Message or error	Cause
401		The token is missing or invalid.
403	Only practitioners can invite patients.	The caller is not a practitioner.
403		Practitioner sharing is off, PATIENT_INVITATION_ENABLED is false, or the caller is not a practitioner of this project.
404		The inviter's practitioner membership is not in the project.
409	code app_url_not_configured	No patient app URL. Fix the configuration; retrying will not help.
409	error invitation_not_configured	No default patient AccessPolicy.
409	error practitioner_without_access_policy	The inviter has full project access.
409		Another write holds the address or the inviter's membership, or the records kept changing. Retry.
429		The practitioner already has 20 pending invitations.
422	A list of path and message	A field is missing or invalid.

Accept

Status	Message or error	Cause
401		The token is missing or invalid.
403		Practitioner sharing is off, PATIENT_INVITATION_ENABLED is false, or the caller is not a patient.
404		No live invitation has this inviteId, the code does not match, the invitation names another patient, or the practitioner's membership is no longer in the project.
409		The invitation was already used, the inviting practitioner is no longer a member, or the records kept changing.
409	error practitioner_without_access_policy	The inviting practitioner has full project access.
410		The invitation expired.
422	A list of path and message	inviteId is not a UUID, or code is shorter than 16 characters.

Gotchas

• Project admins with full access cannot use this route. A member with no AccessPolicy gets 409 practitioner_without_access_policy, because the share would narrow their access. Give inviters a limited AccessPolicy, or onboard patients another way, for example registration.
• 202 says nothing about the outcome. It is the same answer for a new, existing, already-shared or ignored address, so it cannot be used to learn who has an account.
• A failed email is silent. If the message cannot be sent, everything the invitation wrote is undone and the answer is still 202. Map the two templates first.
• The patient controls the share. An invitation is single use and expires after 7 days, and the patient can end the share later with DELETE /v1/patient-sharing/shares/:consentId.
• Sharing is off until an admin turns it on. Check it first when every call answers 403.
• This is a way to create a patient, besides registration. Turning PATIENT_REGISTRATION_ENABLED off does not stop it. Turn off PATIENT_INVITATION_ENABLED or practitioner sharing to stop invitations.
• Your app must serve the link. The email points at your patient app's /accept-invite and /setpassword paths.

Related

• Email templates
• Invitations
• Share a record with a practitioner, the same share started by the patient
• PATIENT_INVITATION_ENABLED