# Accept a patient's record share

Canonical page: https://docs.ovok.com/api/invites/accept-a-patient-s-record-share

`POST /v1/invites/record-share/accept`

Accepts a patient's record share from its email: a practitioner's `PRACTITIONER_PATIENT_SHARED` offer, or a related person's `RELATED_PERSON_INVITED` or `RELATED_PERSON_RECORD_SHARED` invite. From then on the share is in place. The invite decides how it is accepted.

**Auth:** bearer token of the Practitioner or RelatedPerson the invite names; none for an invite to a new address.
**Scope:** the caller's project (from the token); for a new address, the invite's project.

## Behaviour

- Send the `invite` and `code` values from the email's accept link as `inviteId` and `code`. `password` is only for a new related person; send `null` (or leave it out) otherwise.
- Every invite is single use and expires 7 days after it was sent. A used one answers 409, an expired one 410, and an unknown one or a wrong `code` 404, whoever calls.
- On success the invite's Consent becomes `active` and its grant is added to the recipient's membership, in one atomic write. The recipient's cached sessions are refreshed, so the new access applies on the next request.
- The share lasts until the patient ends it (`DELETE /v1/patient-sharing/shares/{consentId}`).

### A practitioner's offer

- Signed in as the practitioner the offer names; without a token the answer is 401.
- Gates: practitioner sharing must be on for the project, and `PRACTITIONER_INVITATION_ENABLED` must not be `false`.
- The share covers the patient's whole compartment. Observations, Communications, DocumentReferences, QuestionnaireResponses, ServiceRequests, Tasks and Appointments can be read, searched, created and updated; CommunicationRequests, Goals, CarePlans, Flags, EpisodeOfCare and DeviceUseStatements are read-only; the Patient can be read, searched and updated. Nothing can be deleted.
- A 409 with `practitioner_without_access_policy` means the caller has full project access, which a share would narrow.
- The answer is the practitioner share: `consentId`, `sharer`, `practitioner`, `startedAt`, `endsAt`.

### A related person's invite

- Gate: patient sharing must be on for the invite's project.
- The share covers the sharer's Observations with the invite's codes (read and search), and the sharer's Patient resource with contact details, identifiers and most other fields hidden.
- A share also covers a multi-value reading's group Observation when it covers every value the group repeats (systolic and diastolic for blood pressure, the waveform for an ECG, any part of an SpO2 or urine-strip reading), so the whole reading can be read and nothing more. The share's `codes` stay as the sharer chose them.
- **A new address** (`RELATED_PERSON_INVITED`): no token. Send a `password` that meets the password policy; without one the answer is a 422 with `password_required`. In one atomic write under the address's account lock, the account is made: a User scoped to the project, a RelatedPerson of the sharer, and a membership holding the built-in related-person base policy (read and search of its own RelatedPerson only, created the first time it is needed) and the share's grant. If the address has any account by now, nothing is written and the answer is a 409 with `address_has_account`. Sign in afterwards with the address and that password.
- **A related person of the project** (`RELATED_PERSON_RECORD_SHARED`): signed in as the related person the invite names; without a token the answer is 401, as another related person or in another project 404. The grant is added to their membership, keeping its base policy.
- The answer is the related-person share: `consentId`, `sharer`, `relatedPerson`, `codes`, `startedAt`, `endsAt`.
- A 409 with `sharing_not_configured` means the project lost its patient-sharing template; turn patient sharing on again.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/record-share/accept' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
  -H 'Content-Type: application/json' \
  -d '{
    "inviteId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
    "code": "<code from the accept link>",
    "password": null
  }'
```

A new related person, without a token:

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/record-share/accept' \
  -H 'Content-Type: application/json' \
  -d '{
    "inviteId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
    "code": "<code from the accept link>",
    "password": "Ex4mple-Passw0rd"
  }'
```