Invitations

Invite practitioner

Invite practitioner using Ovok’s Slim API.

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

NameTypeRequiredDescription
emailstringYesThe invitee's email address. Must be valid. Lowercased.
namestringYesFirst name. At least 1 character.
surnamestringYesLast name. At least 1 character.
accessPolicyIdstring (uuid)YesAccess policy to give the invitee.
projectIdstring (uuid)NoProject to invite to. Must be your project or a direct child of it. Default: your project.
adminbooleanNoAccepted and ignored. Default false.

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 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.
  • 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.
  • 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 Pending in user lists until they set a password.
  • The invitation appears in change history as an Access row with key userInvited. 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.

FieldTypeDescription
membershipobjectThe new project membership, a ProjectMembership resource.
membership.resourceType"ProjectMembership"Always ProjectMembership.
membership.idstring (uuid)Membership id.
membership.projectobjectThe project the invitee joined.
membership.project.referencestringProject/ followed by the project id.
membership.project.displaystringProject name.
membership.userobjectThe invitee's user account.
membership.user.referencestringUser/ followed by the user id.
membership.user.displaystringThe user's display name.
membership.profileobjectThe invitee's practitioner profile.
membership.profile.referencestringPractitioner/ followed by the profile id.
membership.profile.displaystringThe profile's display name.
membership.accessPolicyobjectThe access policy given to the invitee.
membership.accessPolicy.referencestringAccessPolicy/ followed by the policy id.
membership.accessPolicy.displaystringPolicy name.
membership.adminbooleantrue only when the invitee became the first admin of a project that had no owner.
membership.metaobjectResource metadata: project, lastUpdated and more.
profileobjectThe invitee's Practitioner profile.
profile.resourceType"Practitioner"Always Practitioner.
profile.idstring (uuid)Practitioner id.
profile.telecomobject[]One entry with system email and the invitee's address as value.
profile.nameobject[]One entry with given and family.
profile.metaobjectResource metadata: project, lastUpdated and more.
status"Pending"Always Pending. The invitee has not set a password yet.

Errors

StatusMeaning
400The 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.
401The bearer token is missing or invalid.
403The 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.
404No access policy has accessPolicyId.
409Another change to the same account is in progress.
422The body fails validation (unknown fields are refused).

Last updated on

On this page