# Invite a patient into my care

Canonical page: https://docs.ovok.com/api/invites/invite-a-patient-into-my-care

`POST /v1/invites/care`

A signed-in practitioner invites a patient into their care, by email. A new address gets a patient account whose record is already shared with the inviter; a patient of the project gets an invite to accept.

**Auth:** bearer token of a Practitioner.
**Scope:** the caller's project (from the token).

## Behaviour

- **Gates**, checked before the address is looked up, in this order:
  - practitioner sharing (`practitionerSharingEnabled` on `PUT /v1/patient-sharing/settings`) is on; it is off by default;
  - `PATIENT_INVITATION_ENABLED` is not `false`;
  - the project has a patient app URL;
  - the project has a default patient access policy;
  - the inviter's membership has an access policy (a membership with full project access is refused, because a share would narrow it);
  - the inviter has fewer than 20 pending invites.
- **What happens, by address:**
  - No User has the address: a patient account of the project is created with the default patient access policy, and its record is shared with the inviter, in one atomic write. The address gets a `PATIENT_INVITE` email with a set-password link on the patient app.
  - The address belongs to exactly one active patient of the project: a pending invite is created and the address gets a `PATIENT_ASSIGNMENT_REQUEST` email with an accept link, `<patient app URL>/accept-invite?invite=<inviteId>&code=<code>`, valid for 7 days. The share starts only when that patient, signed in, posts both values to `POST /v1/invites/care/accept`.
  - The patient already shares their record with the inviter: nothing is sent, unless their account has no password yet, in which case the set-password email goes out again.
  - Anything else (a User that is not a patient of this project): nothing is written or sent.
- The answer is always `202 { "status": "sent" }`, whichever case applied, so it does not reveal whether the address has an account. If the email cannot be sent, everything the invite wrote is undone, and the answer is still 202.
- Each email is sent as the last step of the write. Map the email templates named above in the project's email configuration first.
- Do not enable practitioner sharing in projects whose practitioners use the carehub dashboard: its route guard checks resource types only, so a practitioner who only holds shared patients could see project-wide data there.
- A 409 with `app_url_not_configured` means the project has no patient app URL; `invitation_not_configured` means it has no default patient access policy; `practitioner_without_access_policy` means the inviter has full project access. None of these is fixed by retrying.
- A 429 means the practitioner already has 20 pending invites.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/care' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "max.mustermann@example.com",
    "firstName": "Max",
    "lastName": "Mustermann"
  }'
```