OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Patient sharing

List shares

  • Sandbox: available
  • Staging: available
  • Production: unknown
GET
/v1/patient-sharing/shares

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

curl -X GET 'https://api.sandbox.ovok.com/v1/patient-sharing/shares' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Response Body

Active outgoing, incoming, practitioner and related-person shares; for a related person, the shares they received.

application/json
  1. response
outgoing*array<>
incoming*array<>
practitioners*array<>
relatedPersons*array<>
received*array<>
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-sharing/shares'
Example Response
{  "outgoing": [    {      "consentId": "string",      "sharer": {        "patientId": "string",        "name": "string"      },      "recipient": {        "patientId": "string",        "name": "string"      },      "codes": [        "string"      ],      "includeMedications": true,      "startedAt": "string",      "endsAt": "string"    }  ],  "incoming": [    {      "consentId": "string",      "sharer": {        "patientId": "string",        "name": "string"      },      "recipient": {        "patientId": "string",        "name": "string"      },      "codes": [        "string"      ],      "includeMedications": true,      "startedAt": "string",      "endsAt": "string"    }  ],  "practitioners": [    {      "consentId": "string",      "sharer": {        "patientId": "string",        "name": "string"      },      "practitioner": {        "practitionerId": "string",        "name": "string"      },      "startedAt": "string",      "endsAt": "string"    }  ],  "relatedPersons": [    {      "consentId": "string",      "sharer": {        "patientId": "string",        "name": "string"      },      "relatedPerson": {        "relatedPersonId": "string",        "name": "string"      },      "codes": [        "string"      ],      "includeMedications": true,      "startedAt": "string",      "endsAt": "string"    }  ],  "received": [    {      "consentId": "string",      "sharer": {        "patientId": "string",        "name": "string"      },      "relatedPerson": {        "relatedPersonId": "string",        "name": "string"      },      "codes": [        "string"      ],      "includeMedications": true,      "startedAt": "string",      "endsAt": "string"    }  ]}

Accept a share invite POST

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 ```bash 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>" }' ```

End a share DELETE

Ends a share, cancels a pending invite, or declines a practitioner's invite. A related person (a carer) leaves a share they received. Access stops at once. **Auth:** bearer token of a Patient or a RelatedPerson. **Scope:** the caller's project (from the token). ## Behaviour - Who may call it, by `consentId`: - a patient-to-patient share: the sharer or the recipient; - a pending patient-to-patient invite: the sharer (this cancels it); - a share of the caller's record with a practitioner, or a practitioner's pending invite to the caller: the patient. - a share of the caller's codes with a related person, or its pending invite: the patient; - a share a patient gave the caller as their related person: the related person (see below). - A practitioner gets 403. - Every grant bound to the Consent is removed from the members who hold it, and the Consent is set to `inactive`, in one atomic write. The holders' cached sessions are refreshed. - Calling it again on an ended share only sweeps any grants left behind, so retrying is safe. - If the records keep changing during the write, it retries up to three times, then answers 409. Retry the call. - Returns `204 No Content`. ## A related person leaving a share - The Consent is set to `inactive`, as when the patient ends it, and its grant leaves the caller's own membership, in one atomic write. The caller's cached sessions are refreshed. - The membership keeps its base policy. One that had lost it gets it back, so it never reads as full project access. - `404` when the share is not one the caller received, for example another carer's or a patient-to-patient share. It never says whose it is. - `409` when the share already ended, or a record changed during the write. Read the list again and retry. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/patient-sharing/shares/c3499c27-2973-0a7f-807e-fb8676a92dcb' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```