Settings

CLINICIAN_INVITE_ON_BUSINESS_EMAIL

Turn a patient registration with a work email into a practitioner invitation, what it needs, and when it silently falls back to a patient account.

When on, a patient registration with a business email address does not create a patient. Ovok creates a practitioner account and emails an invitation instead. Use it when the people who find your patient sign-up page are often clinicians.

TypeBoolean setting
Change withPUT /v1/project/settings/CLINICIAN_INVITE_ON_BUSINESS_EMAIL
Who can change itProject admin
When unsetOff, and GET /v1/project/settings reports false
Set on new projectsNot set by any project-creation route
InheritedNo. A child project reads only its own value.
AffectsPOST /v1/auth/tenant/Patient/register

Turn it on

Set up what the invitation needs first (see below), then switch it on:

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

The response is the full settings record, and the change applies to the next request.

What it needs

Every row must hold for the invitation to go out. If one fails, the person is registered as a patient and the caller is not told; the reason is only logged.

ConditionIf it is not met
The setting is true and the address is a business address, meaning neither free mail nor a throwaway domain.A normal patient registration.
Patient registration would otherwise succeed: PATIENT_REGISTRATION_ENABLED is not false and the project has a default patient AccessPolicy.The registration 403.
DEFAULT_PRACTITIONER_ACCESS_POLICY resolves to a valid policy.A normal patient registration.
A PRACTITIONER_APP_URL resolves. The request's Origin is never used for this link.A normal patient registration.
A PATIENT_APP_URL resolves, for the "continue as a patient" link. The older PATIENT_SIGNUP_URL is used whole when it is set.The practitioner account is undone, and a normal patient registration follows.
The invitation email can be sent: CLINICIAN_SIGNUP_INVITE is mapped and its provider is ready.The practitioner account is undone, and a normal patient registration follows.
No account holds the address in any project.400 Registration failed.

What happens

The registration call answers { "nextStep": "clinician-invite" } with no tokens. Your sign-up screen has to handle that answer, not only a signed-in one.

The person receives an email with two links:

LinkShape
Set a password as a practitioner<practitioner app URL>/setpassword/<id>/<secret>
Continue as a patient<patient signup page>?continueAsPatientToken=<token>

The patient link is valid for 7 days, and only for the same email in the same project. The person sends the token back in the registration call as continueAsPatientToken to register as a patient anyway. An invalid or expired token answers 400 The continue-as-patient link is invalid or has expired. The practitioner's set-password invitation link works for 7 days after it is sent; see the shared invitation-link rule.

The invited practitioner receives the default practitioner AccessPolicy and is not a project admin.

Gotchas

  • The fallback is silent. A missing app URL, policy or email setup turns the call into an ordinary patient registration with tokens. Test the whole path with a work address before you rely on it.
  • A free-mail or throwaway address is a normal patient registration. Only business addresses are invited.
  • It does not read PRACTITIONER_INVITATION_ENABLED. Turning invitations off does not stop this path; turn this setting off to stop it.
  • An email that already has an account anywhere fails. The registration answers 400 Registration failed., because Ovok will not reuse an account that may already have a password and other projects.
  • Rate limit. The registration route allows 5 requests per minute per IP address.
  • Error identifiers are not in one field. See errors and troubleshooting.

Last updated on

On this page