OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Patient sharing

Accept a share invite

  • Sandbox: available
  • Staging: available
  • Production: unknown
POST
/v1/patient-sharing/invites/redeem

The signed-in patient accepts another patient's share invite, and from then on can read what it shares.

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

Behaviour

  • Patient sharing must be on for the project.
  • The invite is single use, expires 15 minutes after it was created, and cannot be accepted by the patient who made it.
  • On success the invite's Consent becomes active and names the caller as recipient, and a grant is added to the caller's membership, in one atomic write. The caller's cached sessions are refreshed, so the new access applies on the next request.
  • The grant lets the caller read and search the sharer's Observations with the shared codes, and read the sharer's Patient resource with contact details, identifiers and most other fields hidden.
  • A share also grants 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 409 that says your account changed meanwhile can be retried as is.
  • A 503 means sharing is on but its template AccessPolicy is missing.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/patient-sharing/invites/redeem' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{    "inviteId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",    "code": "<code from the invite>"  }'

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
inviteId*string
Formatuuid
code*string
Length16 <= length <= 128

Response Body

The share that started.

application/json
  1. response
consentId*string
sharer*
recipient*
codes*array<string>
includeMedications*boolean
startedAt*string
endsAt*string
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-sharing/invites/redeem' \  -H 'Content-Type: application/json' \  -d '{  "inviteId": "14ca54c2-5d85-4c93-81b5-495a2e7e0ca4",  "code": "stringstringstri"}'
Example Response
{  "consentId": "string",  "sharer": {    "patientId": "string",    "name": "string"  },  "recipient": {    "patientId": "string",    "name": "string"  },  "codes": [    "string"  ],  "includeMedications": true,  "startedAt": "string",  "endsAt": "string"}

Create a share invite POST

The signed-in patient creates a one-time invite to share Observations with the given codes with another patient. Set `includeMedications` to `true` to also share patient-scoped MedicationStatements and MedicationAdministrations. Hand the `inviteId` and `code` to the other patient, who accepts with `POST /v1/patient-sharing/invites/redeem`. **Auth:** bearer token of a Patient. **Scope:** the caller's project (from the token). ## Behaviour - Patient sharing must be on for the project (`PUT /v1/patient-sharing/settings`). - `codes`: 1 to 100 Observation codes, each 1 to 64 letters, digits, `.` or `-`. Duplicates are removed. - `includeMedications`: optional, defaults to `false`. When true, the recipient can read the sharer's MedicationStatements and MedicationAdministrations until the share ends. - `endsAt` must be `null`: a share lasts until it is ended. A date is refused for now. - The invite is stored as a draft `Consent`. Only a SHA-256 hash of `code` is stored, so `code` is returned once, in this response. - The invite expires 15 minutes after it is created (`expiresAt`). - A patient can hold at most 10 unexpired invites at once. - A 429 means the patient already holds 10 unexpired invites. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-sharing/invites' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "codes": ["8480-6", "8462-4"], "endsAt": null, "includeMedications": true }' ```

List shares GET

Lists the signed-in patient's active shares in both directions, the practitioners their whole record is shared with, and the related persons they share codes with. For a signed-in related person (a carer), lists the shares patients gave them. **Auth:** bearer token of a Patient or a RelatedPerson. **Scope:** the caller's project (from the token). ## Behaviour - `outgoing`: the caller's active patient-to-patient shares (Consents where the caller is the sharer), including the `includeMedications` choice. - `incoming`: what is shared with the caller, read from the grants on the caller's own membership, since those decide what the caller can see. Each share includes its `includeMedications` choice. A grant whose Consent cannot be read is still listed, so it can be ended. - `practitioners`: the caller's active record shares with practitioners. - `relatedPersons`: the caller's active shares with related persons (carers), each with its `codes` and `includeMedications` choice. - `received`: for a related person, the active shares patients gave them: the sharing patient (`sharer`), the shared `codes`, `includeMedications` and `startedAt`. Only their own: another carer's shares never show. Empty for a patient. - A related person gets only `received`; the other lists are empty. - Names are the display names of the Patient, Practitioner and RelatedPerson profiles in the project. - A practitioner gets 403. - Each Consent search returns at most 100 entries; there is no paging. - Pending invites (drafts) are not listed. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/patient-sharing/shares' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```