# PATIENT_INVITATION_ENABLED

Canonical page: https://docs.ovok.com/settings-and-features/settings/patient-invitation-enabled

Controls whether the project can invite patients by email. An invitation creates the patient account and emails a link where the patient sets a password.

| | |
| --- | --- |
| Type | Boolean setting |
| Change with | `PUT /v1/project/settings/PATIENT_INVITATION_ENABLED` |
| Who can change it | Project admin |
| When unset | Patient invitations are **on**, although `GET /v1/project/settings` reports `false` |
| Set on new projects | `false` for child projects created with `POST /v1/slim/project/child`; not set by any other project-creation route |
| Needs | A default patient AccessPolicy ([`DEFAULT_PATIENT_ACCESS_POLICY`](/settings-and-features/settings/default-patient-access-policy)) and a [patient app URL](/settings-and-features/settings/patient-app-url) |
| Inherited | The switch is not. The app URL can fall back to the parent project. |

## Turn patient invitations off [#turn-patient-invitations-off]

```bash
curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/project/settings/PATIENT_INVITATION_ENABLED' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"enabled":false}'
```

## Where the switch applies [#where-the-switch-applies]

| Route | Who calls it | Notes |
| --- | --- | --- |
| `POST /auth/invite` with `type` `Patient` | No bearer token required; the project comes from `projectId` in the body | The invitation switch is the only gate besides the default patient AccessPolicy. |
| [`POST /v1/invites/care`](/invitations/invite-a-patient), and the deprecated `POST /v1/invites/patient` | A practitioner of the project | Patient sharing must also be on, see [PATIENT_SHARING_ENABLED](/settings-and-features/settings/patient-sharing-enabled). |
| `POST /v1/invites/care/accept`, and the deprecated `POST /v1/invites/patient/accept` | The invited patient | Patient sharing must also be on. |

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

The invitation email carries a link of the form `<patient app URL>/setpassword/<id>/<secret>`. The app URL is resolved from `PATIENT_APP_URL` on the project, then its parent project, then older fallbacks; the request's `Origin` header is never used for a patient link. See [PATIENT_APP_URL](/settings-and-features/settings/patient-app-url).
The set-password invitation link works for 7 days after it is sent; see [the shared invitation-link rule](/invitations#limits-and-shared-behaviour).

| Condition | Status | Response |
| --- | --- | --- |
| Switch is off | `403` | `Invitation is not enabled for this project.` |
| Project has no default patient AccessPolicy | `403` | The same message as above. |
| No patient app URL resolves | `409` | `code` [`app_url_not_configured`](/errors/app-url-not-configured). Nothing is created. |
| `/v1/invites/care` with sharing off | `403` | `Practitioner sharing is not enabled for this project.` |
| `/v1/invites/care` with no default patient policy | `409` | `error` [`invitation_not_configured`](/errors/invitation-not-configured) |

`POST /v1/invites/care` always answers `202` with `{"status":"sent"}` when it succeeds.

## Gotchas [#gotchas]

- **Off and "not configured" look the same.** `POST /auth/invite` answers the same `403` whether the switch is off or the project has no default patient AccessPolicy. If you turned nothing off and still see it, check the AccessPolicy.
- **This is a second way to create a patient account.** While the switch is on and the project has a default patient AccessPolicy, `POST /auth/invite` with `type` `Patient` needs no sign-in. It creates a patient even when [PATIENT_REGISTRATION_ENABLED](/settings-and-features/settings/patient-registration-enabled) is `false`. To stop self-service patient account creation, turn off **both** switches. The route allows 5 requests per minute per client address.
- **`GET` shows `false` for a project that has never set it, but invitations work.** Set the key to the value you intend.
- **Projects created with `POST /v1/slim/project/child` start with it off.**
- **If the email cannot be sent, the account is rolled back** and the call returns `500`. Retrying is safe. Map `PATIENT_INVITE` and `PATIENT_ASSIGNMENT_REQUEST` first: see [Email templates](/email-templates).
- **Error identifiers are not in one field.** [`app_url_not_configured`](/errors/app-url-not-configured) is in `code`; [`invitation_not_configured`](/errors/invitation-not-configured) is in `error`. Match on both.

## Related [#related]

- [Email templates](/email-templates), for the messages an invitation sends
- [Invitations](/invitations), the routes this switch gates
- [PATIENT_APP_URL](/settings-and-features/settings/patient-app-url)
- [PATIENT_REGISTRATION_ENABLED](/settings-and-features/settings/patient-registration-enabled)
- [PRACTITIONER_INVITATION_ENABLED](/settings-and-features/settings/practitioner-invitation-enabled)
- [RELATED_PERSON_INVITATION_ENABLED](/settings-and-features/settings/related-person-invitation-enabled), which gates carer invitations instead
