# Invite a patient into care

Canonical page: https://docs.ovok.com/invitations/invite-a-patient

A signed-in **practitioner** invites a patient by email. If the address is new, Ovok creates a patient account whose record is already shared with the inviter. If it belongs to a patient of the project, that patient receives an invitation to accept.

| Step | Method | Path | Who |
| --- | --- | --- | --- |
| 1. Invite | `POST` | `/v1/invites/care` | A practitioner |
| 2. Accept (existing patients only) | `POST` | `/v1/invites/care/accept` | The invited patient |

## What the project needs [#what-the-project-needs]

Every row must hold before the address is looked up.

| Requirement | Detail |
| --- | --- |
| Practitioner sharing on | `practitionerSharingEnabled`, set with [`PUT /v1/patient-sharing/settings`](/settings-and-features/settings/patient-sharing-enabled). **Off by default.** |
| Patient invitations on | [`PATIENT_INVITATION_ENABLED`](/settings-and-features/settings/patient-invitation-enabled) must not be `false`. |
| A patient app URL | [`PATIENT_APP_URL`](/settings-and-features/settings/patient-app-url). The request's `Origin` is never used here. |
| A default patient AccessPolicy | The [`DEFAULT_PATIENT_ACCESS_POLICY`](/settings-and-features/settings/default-patient-access-policy) setting. |
| An inviter with an AccessPolicy | The practitioner's membership must have one. A member with full project access is refused. |
| Fewer than 20 pending invitations | Per practitioner. |
| Two email templates mapped | `PATIENT_INVITE` and `PATIENT_ASSIGNMENT_REQUEST`, [mapped](/email-templates/map-templates) with a provider that is `ready`. |

## Step 1: Invite [#step-1-invite]

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/care' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"email":"jane@example.com","firstName":"Jane","lastName":"Doe"}'
```

| Body field | Required | Description |
| --- | --- | --- |
| `email` | Yes | A valid address, up to 254 characters. Ovok lowercases it. |
| `firstName` | Yes | 1 to 200 characters. Used when a new account is created. |
| `lastName` | Yes | 1 to 200 characters. |

The answer is always `202 Accepted`, with the same response for every address outcome below:

| Field | Value |
| --- | --- |
| `status` | `sent` |

### What happens, by address [#what-happens-by-address]

| The address… | What Ovok does |
| --- | --- |
| Has no account | Creates a patient of the project with the default patient AccessPolicy and shares the record with the inviter, in one write, and emails a set-password link (`PATIENT_INVITE`). |
| Belongs to exactly one active patient of the project | Creates a pending invitation and emails an accept link (`PATIENT_ASSIGNMENT_REQUEST`), valid for 7 days. The share starts only when step 2 succeeds. |
| Already shares their record with the inviter | Sends nothing, unless their account still has no password, in which case the set-password email goes out again. |
| Anything else | Writes and sends nothing. For example an account that is not a patient of this project. |

A set-password link for a new patient works for 7 days after it is sent. After that, invite the person again; see [the shared invitation-link rule](/invitations#limits-and-shared-behaviour).

## Step 2: Accept [#step-2-accept]

The patient opens `<patient app URL>/accept-invite?invite=<inviteId>&code=<code>` in your app, signs in, and your app posts both values:

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/care/accept' \
  --header "Authorization: Bearer ${PATIENT_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"inviteId":"8c1e5a52-6f0b-4d9e-9a41-0b2f7c3d9e10","code":"<code from the link>"}'
```

| Body field | Description |
| --- | --- |
| `inviteId` | The `invite` value from the link. A UUID. |
| `code` | The `code` value from the link, 16 to 128 characters. |

On success the answer is `200` with the share (the same shape as [sharing with a practitioner](/invitations/share-with-practitioner#step-2-accept)). The practitioner then holds the patient's whole record, with the same access described there: no deletes, and the Patient can be read, searched and updated.

## What can go wrong [#what-can-go-wrong]

**Invite**

| Status | Message or `error` | Cause |
| --- | --- | --- |
| `401` | | The token is missing or invalid. |
| `403` | `Only practitioners can invite patients.` | The caller is not a practitioner. |
| `403` | | Practitioner sharing is off, [`PATIENT_INVITATION_ENABLED`](/settings-and-features/settings/patient-invitation-enabled) is `false`, or the caller is not a practitioner of this project. |
| `404` | | The inviter's practitioner membership is not in the project. |
| `409` | `code` [`app_url_not_configured`](/errors/app-url-not-configured) | No patient app URL. Fix the configuration; retrying will not help. |
| `409` | `error` [`invitation_not_configured`](/errors/invitation-not-configured) | No default patient AccessPolicy. |
| `409` | `error` [`practitioner_without_access_policy`](/errors/practitioner-without-access-policy) | The inviter has full project access. |
| `409` | | Another write holds the address or the inviter's membership, or the records kept changing. Retry. |
| `429` | | The practitioner already has 20 pending invitations. |
| `422` | A list of `path` and `message` | A field is missing or invalid. |

**Accept**

| Status | Message or `error` | Cause |
| --- | --- | --- |
| `401` | | The token is missing or invalid. |
| `403` | | Practitioner sharing is off, [`PATIENT_INVITATION_ENABLED`](/settings-and-features/settings/patient-invitation-enabled) is `false`, or the caller is not a patient. |
| `404` | | No live invitation has this `inviteId`, the `code` does not match, the invitation names another patient, or the practitioner's membership is no longer in the project. |
| `409` | | The invitation was already used, the inviting practitioner is no longer a member (or more than one account acts as them), or the records kept changing. |
| `409` | `error` [`practitioner_without_access_policy`](/errors/practitioner-without-access-policy) | The inviting practitioner has full project access. |
| `410` | | The invitation expired. |
| `422` | A list of `path` and `message` | `inviteId` is not a UUID, or `code` is shorter than 16 characters. |

## Deprecated routes [#deprecated-routes]

Until 1 December 2026 the same flow also answers on `POST /v1/invites/patient` and `POST /v1/invites/patient/accept`, with the same body, behaviour and status codes. Both are deprecated; see [Deprecated routes](/production/deprecated-routes#invitations-deprecated-22-october-2026).

## Gotchas [#gotchas]

- **Project admins with full access cannot use this route.** A member with no AccessPolicy gets `409` [`practitioner_without_access_policy`](/errors/practitioner-without-access-policy), because the share would narrow their access. Give inviters a limited AccessPolicy, or onboard patients another way, for example [registration](/authentication/patient-registration).
- **`202` says nothing about the outcome.** It is the same answer for a new, existing, already-shared or ignored address, so it cannot be used to learn who has an account.
- **A failed email is silent.** If the message cannot be sent, everything the invitation wrote is undone and the answer is still `202`. [Map the two templates](/email-templates/set-up-email) first.
- **The patient controls the share.** An invitation is single use and expires after 7 days, and the patient can end the share later with `DELETE /v1/patient-sharing/shares/:consentId`.
- **Sharing is off until an admin turns it on.** Check it first when every call answers `403`.
- **This is a way to create a patient, besides registration.** Turning [`PATIENT_REGISTRATION_ENABLED`](/settings-and-features/settings/patient-registration-enabled) off does not stop it. Turn off [`PATIENT_INVITATION_ENABLED`](/settings-and-features/settings/patient-invitation-enabled) or practitioner sharing to stop invitations.
- **Your app must serve the link.** The email points at your patient app's `/accept-invite` and `/setpassword` paths.

## Related [#related]

- [Email templates](/email-templates)
- [Invitations](/invitations)
- [Share a record with a practitioner](/invitations/share-with-practitioner), the same share started by the patient
- [PATIENT_INVITATION_ENABLED](/settings-and-features/settings/patient-invitation-enabled)
