Share readings with a carer

A signed-in patient shares chosen readings with a carer, such as a family member, by email. The carer reads only the Observation codes the patient picks, plus the patient's name. In FHIR a carer is a RelatedPerson.

Unlike a practitioner share, every carer invite must be accepted, and a new address gets its account at that moment. A carer account cannot be made any other way. See Carers for signing in and what a carer can do.

What the project needsCopy Anchor Link

Every row must hold before the address is looked up.

No default AccessPolicy is needed. Ovok creates the carer's built-in policy the first time one is needed.

Step 1: InviteCopy Anchor Link

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/record-share' \
  --header "Authorization: Bearer ${PATIENT_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "recipient": "related-person",
    "email": "sam@example.com",
    "firstName": "Sam",
    "lastName": "Doe",
    "codes": ["8480-6", "8462-4"]
  }'

The answer is always 202 Accepted with { "status": "sent" }, whatever the address turned out to be.

What happens, by addressCopy Anchor Link

The pending invite holds only a hash of the one-time code and grants nothing until it is accepted. The link is <patient app URL>/accept-invite?invite=<inviteId>&code=<code>, and it works for 7 days.

Step 2: AcceptCopy Anchor Link

Your patient app serves /accept-invite. It reads invite and code from the link and posts them. How depends on whether the carer already has an account.

A new carer: choose a password, no tokenCopy Anchor Link

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/record-share/accept' \
  --header 'Content-Type: application/json' \
  --data '{
    "inviteId": "8c1e5a52-6f0b-4d9e-9a41-0b2f7c3d9e10",
    "code": "<code from the link>",
    "password": "<the password the carer chose>"
  }'

Holding the code proves the address is theirs, so no token is needed. In one write, Ovok creates the carer's user, a RelatedPerson linked to the patient, and a membership with the share. The carer then signs in with the address and that password. The answer contains no tokens.

An existing carer: signed inCopy Anchor Link

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/invites/record-share/accept' \
  --header "Authorization: Bearer ${CARER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"inviteId":"8c1e5a52-6f0b-4d9e-9a41-0b2f7c3d9e10","code":"<code from the link>","password":null}'

The new share is added to the carer's account, next to any shares from other patients.

Which form to showCopy Anchor Link

The link looks the same in both emails. To choose the screen, post the link's values with no token and "password": null:

The code is checked first, so a wrong or used code answers 404, 409 or 410 before either of these.

The answerCopy Anchor Link

On success the answer is 200 with the share:

The change applies on the carer's next request.

What the carer can readCopy Anchor Link

Nothing else, and nothing can be written or deleted. Another code, another patient's data, or any other resource answers 403 or 404 (an empty search). See Carers.

End a shareCopy Anchor Link

The patient ends a carer share, or cancels a pending invite, with DELETE /v1/patient-sharing/shares/:consentId. Access stops at once. The patient lists their carer shares in relatedPersons of GET /v1/patient-sharing/shares. A carer cannot list or leave shares yet.

What can go wrongCopy Anchor Link

Invite

Accept

GotchasCopy Anchor Link

• Patient sharing gates this, not practitioner sharing. A project with only practitionerSharingEnabled on answers 403. Turn enabled on.
• A new carer has no account until they accept. Until then, a reset or sign-in for that address finds nothing.
• One address, one kind of account. An address that belongs to a patient or practitioner of the project is ignored on invite and refused on accept with address_has_account.
• 202 says nothing about the outcome. It is the same answer whatever the address was. Tell the patient "if the address can receive it, an invitation is on its way".
• A failed email is silent. If the message cannot be sent, the invite is undone and the answer is still 202. Map the templates first.
• Turning invitations off also blocks pending invites. With RELATED_PERSON_INVITATION_ENABLED off, accepting answers 403 and no account is made.
• Carer accounts belong to one project. A carer of two projects has two accounts, one per tenant.

RelatedCopy Anchor Link

• Carers: sign-in, password reset, and what a carer can do
• Invitations
• Share a record with a practitioner, the same route with recipient: "practitioner"
• RELATED_PERSON_INVITATION_ENABLED
• PATIENT_SHARING_ENABLED