Skip to main content

CLINICIAN_INVITE_ON_BUSINESS_EMAIL

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 /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 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.