# Invite practitioner

Canonical page: https://docs.ovok.com/slim-apis/invite/invite-practitioner

| Method | Path |
| --- | --- |
| `POST` | `/v1/slim/invite/practitioner` |

[Authentication](/authentication) · [Access policies](/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 [#request]

### Body [#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 [#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](/invitations#limits-and-shared-behaviour). 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](/slim-apis/audit/list-change-history) as an `Access` row with key `userInvited`. See the [key catalogue](/slim-apis/audit/change-history-keys).
- Returns the new membership, the practitioner profile and `status: "Pending"`.


## Example [#example]

```bash
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 [#successful-response]

`201` — Practitioner invited successfully.

```json
{
  "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`](/api/fhir/r4/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 [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | 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`](/errors/unauthenticated) | The bearer token is missing or invalid. |
| [`403`](/errors/forbidden) | 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`](/errors/not-found) | No access policy has `accessPolicyId`. |
| [`409`](/errors/conflict) | Another change to the same account is in progress. |
| [`422`](/errors/validation-failed) | The body fails validation (unknown fields are refused). |
