Getting Started

Copy page

Introduction to the Shared Health Record

The Shared Health Record (SHR) is the national clinical record. It holds the encounters, observations, conditions, medications and other FHIR resources a patient accumulates across every facility they visit, so a clinician at one facility can see what happened at another.

Two things make the SHR different from the other HIE services you integrate with:

• Everything is FHIR. You write clinical data as a FHIR Bundle and you read it back as a FHIR search result. The middleware passes both through to the Digital Health Agency (DHA) platform largely unchanged.
• Nothing happens without patient consent. The patient must consent before their record can be read, and that consent is bound to a single visit. Consent produces a consent token that you send on every read.

---

1. The lifecycle at a glance

Working with the SHR is a four-stage lifecycle: consent, visit, write, read.

Stage 1: Request consent

Call POST /shr/consents with the facility's FR code, the patient's Client Registry (CR) ID, the visit type (OP or IP) and who is asking. DHA sends the patient an OTP and returns a consent_id plus an otp_record.

If the patient never receives the OTP, call POST /shr/consents/{consent_id}/resend-otp. It returns a new otp_record - verify with that one, not the original.

You can poll GET /shr/consents/{consent_id}/status at any point to see where the request stands.

Stage 2: Verify consent and open the visit

Call POST /shr/consents/{consent_id}/verify with the otp_record and the OTP the patient read out. On success you get back two values that drive everything else:

Value	What it is for
consent_token	Sent in the X-Consent-Token header on every read of patient records.
visit_id	Identifies the visit the consent opened. Used to refresh consent and to close the visit.

Stage 3: Write clinical data

Call POST /shr/bundles with a FHIR collection Bundle. Two referencing rules matter:

• the Encounter must reference the visit's EpisodeOfCare, and
• every clinical resource in the bundle must reference that Encounter.

The middleware only checks that the body is a Bundle (resourceType is Bundle); everything else is validated upstream by DHA, so a structurally valid bundle can still be rejected on its contents.

Stage 4: Read patient records

Call GET /shr/patient-records with the patient's cr_id, the requesting practitioner_id, the resources you want (comma separated) and the X-Consent-Token header. Page through large result sets with page_token.

Before you interpret what came back - or decide what a consent needs to cover - look up the security labels that govern a resource type or code with GET /shr/resource-labels.

Closing out

When the encounter is over, call POST /shr/visits/{visit_id}/close. If the visit is still open but the token has expired, call POST /shr/visits/{visit_id}/refresh to get a fresh one.

---

2. Endpoint summary

Endpoint	Purpose
POST /shr/consents	Start a consent request. Returns consent_id and otp_record.
POST /shr/consents/{consent_id}/verify	Verify with the OTP. Returns consent_token and visit_id.
GET /shr/consents/{consent_id}/status	Poll the state of a consent request.
POST /shr/consents/{consent_id}/resend-otp	Resend the OTP. Returns a new otp_record.
POST /shr/visits/{visit_id}/refresh	Refresh the consent token for an open visit.
POST /shr/visits/{visit_id}/close	Close the visit.
POST /shr/bundles	Write a FHIR collection Bundle to the record.
GET /shr/patient-records	Read a patient's records against a consent token.
GET /shr/resource-labels	Look up the security labels for a resource type or code.

---

3. Before you start

• Get the patient's CR ID first. Consent is requested against a Client Registry identifier, not a national ID. Resolve it through Patient Search if you do not already hold it.
• Know your practitioner ID. Reads are attributed to a practitioner from the Health Worker Registry, and the practitioner_id is mandatory on every records fetch.
• Standardise your codes. Clinical content you write should be bound to the code systems the Terminology Service publishes, so other facilities can read what you wrote.

4. Related resources

• Shared Health Record API reference
• Introduction to the Terminology Service
• Patient Search