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.
| Type | Boolean setting |
| Change with | PUT /v1/project/settings/PATIENT_INVITATION_ENABLED |
| Who can change it | Project admin |
| When unset | Patient invitations are on, although GET /v1/project/settings reports false |
| Set on new projects | false for child projects created with POST /v1/slim/project/child; not set by any other project-creation route |
| Needs | A default patient AccessPolicy (DEFAULT_PATIENT_ACCESS_POLICY) and a patient app URL |
| Inherited | The 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
| Route | Who calls it | Notes |
|---|---|---|
POST /auth/invite with type Patient | No bearer token required; the project comes from projectId in the body | The invitation switch is the only gate besides the default patient AccessPolicy. |
POST /v1/invites/care, and the deprecated POST /v1/invites/patient | A practitioner of the project | Patient sharing must also be on, see PATIENT_SHARING_ENABLED. |
POST /v1/invites/care/accept, and the deprecated POST /v1/invites/patient/accept | The invited patient | Patient 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.
| Condition | Status | Response |
|---|---|---|
| Switch is off | 403 | Invitation is not enabled for this project. |
| Project has no default patient AccessPolicy | 403 | The same message as above. |
| No patient app URL resolves | 409 | code app_url_not_configured. Nothing is created. |
/v1/invites/care with sharing off | 403 | Practitioner sharing is not enabled for this project. |
/v1/invites/care with no default patient policy | 409 | error 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/inviteanswers the same403whether 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/invitewithtypePatientneeds no sign-in. It creates a patient even when PATIENT_REGISTRATION_ENABLED isfalse. To stop self-service patient account creation, turn off both switches. The route allows 5 requests per minute per client address. GETshowsfalsefor 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/childstart with it off. - If the email cannot be sent, the account is rolled back and the call returns
500. Retrying is safe. MapPATIENT_INVITEandPATIENT_ASSIGNMENT_REQUESTfirst: see Email templates. - Error identifiers are not in one field.
app_url_not_configuredis incode;invitation_not_configuredis inerror. Match on both.
Related
- Email templates, for the messages an invitation sends
- Invitations, the routes this switch gates
- PATIENT_APP_URL
- PATIENT_REGISTRATION_ENABLED
- PRACTITIONER_INVITATION_ENABLED
- RELATED_PERSON_INVITATION_ENABLED, which gates carer invitations instead
Last updated on