Invite practitioner
Invite practitioner using Ovok’s Slim API.
| 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.
Request
Body
The body is strict: a field that is not listed here fails validation.
| Name | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The invitee's email address. Must be valid. Lowercased. |
name | string | Yes | First name. At least 1 character. |
surname | string | Yes | Last name. At least 1 character. |
accessPolicyId | string (uuid) | Yes | Access policy to give the invitee. |
projectId | string (uuid) | No | Project to invite to. Must be your project or a direct child of it. Default: your project. |
admin | boolean | No | Accepted and ignored. Default false. |
Behaviour
- Practitioner invitations must be enabled on the target project. They are enabled unless the project turns them off.
accessPolicyIdmust 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
emailin the target project is refused: an invite never changes a member's role or admin flag (usePUT /v1/slim/policy/{id}). An existing practitioner account elsewhere, your own project included, is reused: only the membership and practitioner profile are new. A patient account of another project is not: it is that project's own, and the invitee gets a practitioner account of their own. - 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 and works for 7 days; see the shared invitation-link rule. If the email fails, the account is undone and the request answers 400.
adminin the body is ignored. The invitee becomes an admin member, and the project owner, only when the target project has no owner yet.- A reused account that already has a password, or that belongs to another project, gets no invitation email. The invitee signs in with the password they already have.
- The invitee shows as
Pendingin user lists until they set a password. - The invitation appears in change history as an
Accessrow with keyuserInvited. See the key catalogue. - 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": "d2c8f4a0-6b3e-4175-9e2d-8a1c5f7b3e46"
}'Successful response
201 — Practitioner invited successfully.
{
"membership": {
"resourceType": "ProjectMembership",
"id": "e4a6c8f0-2b1d-4973-8a5e-7d9f1b3c5e24",
"project": { "reference": "Project/b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "display": "Demo project" },
"user": { "reference": "User/f1b3d5e7-9a2c-4846-b0d8-2c4e6a8f0b13", "display": "Anna Beispiel" },
"profile": { "reference": "Practitioner/7c9e1a3b-5d4f-4b82-a6c0-8e2f4a6b8d35", "display": "Anna Beispiel" },
"accessPolicy": { "reference": "AccessPolicy/d2c8f4a0-6b3e-4175-9e2d-8a1c5f7b3e46", "display": "Practitioner" },
"admin": false,
"meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "lastUpdated": "2026-10-09T08:20:00.000Z" }
},
"profile": {
"resourceType": "Practitioner",
"id": "7c9e1a3b-5d4f-4b82-a6c0-8e2f4a6b8d35",
"telecom": [{ "system": "email", "value": "team@example.com" }],
"name": [{ "given": ["Anna"], "family": "Beispiel" }],
"meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "lastUpdated": "2026-10-09T08:20:00.000Z" }
},
"status": "Pending"
}membership and profile are returned as the FHIR server stored them, so they can carry more fields than shown, such as meta.versionId.
| Field | Type | Description |
|---|---|---|
membership | object | The new project membership, a ProjectMembership resource. |
membership.resourceType | "ProjectMembership" | Always ProjectMembership. |
membership.id | string (uuid) | Membership id. |
membership.project | object | The project the invitee joined. |
membership.project.reference | string | Project/ followed by the project id. |
membership.project.display | string | Project name. |
membership.user | object | The invitee's user account. |
membership.user.reference | string | User/ followed by the user id. |
membership.user.display | string | The user's display name. |
membership.profile | object | The invitee's practitioner profile. |
membership.profile.reference | string | Practitioner/ followed by the profile id. |
membership.profile.display | string | The profile's display name. |
membership.accessPolicy | object | The access policy given to the invitee. |
membership.accessPolicy.reference | string | AccessPolicy/ followed by the policy id. |
membership.accessPolicy.display | string | Policy name. |
membership.admin | boolean | true only when the invitee became the first admin of a project that had no owner. |
membership.meta | object | Resource metadata: project, lastUpdated and more. |
profile | object | The invitee's Practitioner profile. |
profile.resourceType | "Practitioner" | Always Practitioner. |
profile.id | string (uuid) | Practitioner id. |
profile.telecom | object[] | One entry with system email and the invitee's address as value. |
profile.name | object[] | One entry with given and family. |
profile.meta | object | Resource metadata: project, lastUpdated and more. |
status | "Pending" | Always Pending. The invitee has not set a password yet. |
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). |
Last updated on