Invite practitioner

Method	Path
POST	/v1/slim/invite/practitioner

Authentication · Access policies

Invites a practitioner to your project, or to one of its direct child projects, and emails them a link to set their password.

Auth: Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant Practitioner:create (project admins skip this check). Scope: The caller's project (from the token), or projectId when given. projectId must be the caller's project or a direct child of it.

Behaviour

• Practitioner invitations must be enabled on the target project. They are enabled unless the project turns them off.
• accessPolicyId must name a policy of your project, its parent or a direct child, at or below your own rank. It is checked before anything is written.
• An existing practitioner account with this email in the target project is refused: an invite never changes a member's role or admin flag (use PUT /v1/slim/policy/{id}). An existing user account elsewhere, your own project included, is reused: only the membership and practitioner profile are new.
• Ovok creates the membership with the access policy and the practitioner profile, then emails an invitation with a password-setup link. The link points to the app the request came from. If the email fails, the account is undone and the request answers 400.
• admin in the body is ignored. The invitee becomes an admin member, and the project owner, only when the target project has no owner yet.
• The invitee shows as Pending in user lists until they set a password.
• Returns the new membership, the practitioner profile and status: "Pending".

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/slim/invite/practitioner' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "team@example.com",
    "name": "Anna",
    "surname": "Beispiel",
    "accessPolicyId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
  }'

Successful response

201 — Practitioner invited successfully.

Errors

Status	Meaning
400	The session carries no project, the target project is out of scope, the email already has an account in the target project, or the invitation email could not be sent.
401	The bearer token is missing or invalid.
403	The session is not a practitioner, admin or System Owner session, its access policy lacks Practitioner:create, invitations are disabled on the target project, the access policy is outside your scope, or it ranks above you.
404	No access policy has accessPolicyId.
409	Another change to the same account is in progress.
422	The body fails validation (unknown fields are refused).