Settings

PATIENT_INVITATION_ENABLED

Allow or stop patient invitations, and what an invitation needs before it can be sent.

Controls whether the project can invite patients by email. An invitation creates the patient account and emails a link where the patient sets a password.

TypeBoolean setting
Change withPUT /v1/project/settings/PATIENT_INVITATION_ENABLED
Who can change itProject admin
When unsetPatient invitations are on, although GET /v1/project/settings reports false
Set on new projectsfalse for child projects created with POST /v1/slim/project/child; not set by any other project-creation route
NeedsA default patient AccessPolicy (DEFAULT_PATIENT_ACCESS_POLICY) and a patient app URL
InheritedThe switch is not. The app URL can fall back to the parent project.

Turn patient invitations off

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/project/settings/PATIENT_INVITATION_ENABLED' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"enabled":false}'

Where the switch applies

RouteWho calls itNotes
POST /auth/invite with type PatientNo bearer token required; the project comes from projectId in the bodyThe invitation switch is the only gate besides the default patient AccessPolicy.
POST /v1/invites/care, and the deprecated POST /v1/invites/patientA practitioner of the projectPatient sharing must also be on, see PATIENT_SHARING_ENABLED.
POST /v1/invites/care/accept, and the deprecated POST /v1/invites/patient/acceptThe invited patientPatient sharing must also be on.

What the invitation needs

The invitation email carries a link of the form <patient app URL>/setpassword/<id>/<secret>. The app URL is resolved from PATIENT_APP_URL on the project, then its parent project, then older fallbacks; the request's Origin header is never used for a patient link. See PATIENT_APP_URL. The set-password invitation link works for 7 days after it is sent; see the shared invitation-link rule.

ConditionStatusResponse
Switch is off403Invitation is not enabled for this project.
Project has no default patient AccessPolicy403The same message as above.
No patient app URL resolves409code app_url_not_configured. Nothing is created.
/v1/invites/care with sharing off403Practitioner sharing is not enabled for this project.
/v1/invites/care with no default patient policy409error invitation_not_configured

POST /v1/invites/care always answers 202 with {"status":"sent"} when it succeeds.

Gotchas

  • Off and "not configured" look the same. POST /auth/invite answers the same 403 whether the switch is off or the project has no default patient AccessPolicy. If you turned nothing off and still see it, check the AccessPolicy.
  • This is a second way to create a patient account. While the switch is on and the project has a default patient AccessPolicy, POST /auth/invite with type Patient needs no sign-in. It creates a patient even when PATIENT_REGISTRATION_ENABLED is false. To stop self-service patient account creation, turn off both switches. The route allows 5 requests per minute per client address.
  • GET shows false for a project that has never set it, but invitations work. Set the key to the value you intend.
  • Projects created with POST /v1/slim/project/child start with it off.
  • If the email cannot be sent, the account is rolled back and the call returns 500. Retrying is safe. Map PATIENT_INVITE and PATIENT_ASSIGNMENT_REQUEST first: see Email templates.
  • Error identifiers are not in one field. app_url_not_configured is in code; invitation_not_configured is in error. Match on both.

Last updated on

On this page