My Health Record Integration: A Practical Guide

This guide is for software teams — clinical information system (CIS) vendors, health tech startups, and hospital integration teams — planning a My Health Record integration. It maps the full path from developer registration to production connection: the environments, the conformance gates, the CDA document plumbing, and the failure modes that reliably cost teams weeks.

Everything here reflects the process as run by the Australian Digital Health Agency (the Agency). Details change; where a step is likely to move, this guide links to the authoritative source rather than freezing a number that will go stale.

The My Health Record integration pathways

There isn't one way to connect. Which pathway you take determines your conformance scope, so settle it before writing code.

B2B Gateway — the main pathway for clinical software. SOAP web services secured with NASH PKI certificates and WS-Security. This is how documents get uploaded and retrieved by a CIS, and it is what most of this guide covers. See the B2B Gateway service pages on the Agency's developer portal.
Direct CIS connection vs Contracted Service Provider (CSP) — a vendor can connect software operated by each healthcare organisation under that organisation's own identifiers, or operate a hosted platform under the CSP model, where your organisation registers as a CSP and transacts on behalf of client organisations. The CSP route changes registration, certificates, and the identifiers you present on every call.
HIPS — the Agency's middleware, widely used by public hospitals to bridge patient administration and clinical systems to My Health Record. If you sell into hospitals, you may be integrating with HIPS rather than the gateway itself.
FHIR Gateway — a REST/FHIR API originally built for consumer and mobile applications, focused on reading record content. The Agency is progressively modernising My Health Record around FHIR, but as of this writing clinical document upload from a CIS remains a B2B Gateway concern. Check the FHIR Gateway specifications for current capability before assuming you can avoid SOAP.

Registration: getting access to a test environment

Start at the Digital Health Developer Portal (with newer material also published on the Agency's Implementer Hub). Register your organisation, then request the My Health Record software vendor Welcome Pack. The pack includes the Vendor Product Details (VPD) form — submitting it is what formally registers your product and your intent to connect, and it drives everything downstream: the test data you're issued and the conformance test cases you'll face are tailored to the use cases you nominate on it.

With registration accepted, you get access to the Software Vendor Test (SVT) environment: a stable, production-like instance of My Health Record with test healthcare organisations, test NASH certificates, and dummy patients with valid test IHIs. All development and all formal testing happen here.

Plan for the Healthcare Identifiers (HI) Service at the same time. Every My Health Record transaction is keyed on identifiers — IHI for the patient, HPI-I for the individual provider, HPI-O for the organisation — and the Agency expects your software to source and validate them through the HI Service. If you haven't built that yet, it's a parallel workstream with its own conformance requirements, not a footnote.

Building against the B2B Gateway

The core web services

The gateway is a set of SOAP services. The ones nearly every integration touches:

doesPCEHRExist — check whether the patient has a record (and whether it's accessible) before offering My Health Record features in your UI.
gainPCEHRAccess — establish an access session for the patient's record, including handling records protected by an access code. You must gain access before document operations will succeed.
getDocumentList / getDocument — query the patient's document index and retrieve documents (returned as CDA packages your software must render safely).
uploadDocument — upload a new clinical document as a signed CDA package, or supersede an existing one by referencing the document it replaces.
removeDocument — remove a document your organisation previously uploaded (e.g. wrong patient).

Authentication and message plumbing

Every call runs over mutual TLS using a NASH PKI organisation certificate, and the SOAP body is signed with the same credential. Requests carry a PCEHR header identifying the healthcare organisation (HPI-O), the individual user (HPI-I for providers, or an authorised-employee assertion for non-clinical staff), and your product (vendor, product name, version — as registered on your VPD form).

Don't hand-roll this. The Agency publishes sample client libraries for .NET and Java under the AuDigitalHealth GitHub organisation; they encode the WS-Security profile, header structure, and signing behaviour the gateway actually expects, and they're the fastest way to a first successful doesPCEHRExist call.

CDA documents: authoring, packaging, upload

Clinical content goes up as HL7 CDA documents — Shared Health Summary, Event Summary, Discharge Summary, eReferral, Specialist Letter, prescription and dispense records, pathology and diagnostic imaging reports. Each document type has its own CDA Implementation Guide and Schematron rules published on the developer portal, and each is a separate line item in your conformance scope. Most vendors start with one or two document types, not the full set.

A document isn't uploaded as bare XML. It's a CDA package: a zip containing the CDA root document, any attachments (including the rendered report or referenced images), and a digital signature over the payload, signed with your NASH key. Get the packaging and signature layer right early — it fails in ways that are hard to debug from gateway error responses alone.

The Agency's Clinical Package Validator is the tool for local validation: it runs the Schematron for each document type, checks package structure, and does partial checking of SNOMED CT-AU, AMT and PBS coding. Wire it into your CI. A package that fails the Validator will fail the gateway; the reverse, unfortunately, is not guaranteed — more on that below.

Conformance: NoC, CCD and the vendor declaration

My Health Record conformance has run on an industry self-declaration model since mid-2015, but the connection tests are observed and the artefacts are real. The sequence, per the Agency's software vendor guide to the connection process:

Notice of Connection (NoC) testing — a formal test of your software's web service interactions with the HI Service and My Health Record in SVT, against a test data pack tailored to the use cases on your VPD form. It runs in two stages: a self-paced self-assessment, then an observed session where the Agency's testing partner watches your software execute the test cases (screen-share is fine). Passing earns a Notice of Connection for that specific product version.
Conformance, Compliance and Declaration (CCD) testing — verifies the clinical-safety and usage requirements from the conformance profiles that observation of web service calls can't, e.g. how your UI presents record content and manages consent-related workflows.
Security conformance — the Security Requirements for My Health Record Connecting Systems profile applies to connecting software and, unlike most profiles, involves evidence verification rather than declaration alone.
Conformance Vendor Declaration Form — the final artefact. Submitting it (with your NoC and supporting evidence) is what authorises the software version to connect to production, and lands your product on the Agency's register of conformant software.

How long does it take?

It depends almost entirely on how many use cases and document types you nominate, and on test scheduling. Treat the formal testing phase as a project stage measured in weeks, book observed sessions ahead, and expect a re-run of affected test cases when you change conformance-relevant functionality later — a version bump with new My Health Record features is not a free upgrade. Current process details and forms are on the developer portal; don't rely on second-hand timelines, including this guide's.

Going to production

Conformance authorises your software. Each healthcare organisation running it still needs its own standing: a seed organisation registration with an HPI-O, a production NASH PKI organisation certificate (requested through HPOS), and My Health Record participation obligations accepted. Under the CSP model, your CSP registration and certificate are on the critical path instead, with client organisations linked to you.

Budget onboarding effort accordingly: for a typical clinic customer, identifier registration and certificate issuance is the slowest part of go-live, and it's on the customer's side of the fence. Vendors who script and document this walk-through churn far fewer pilots. The Agency's guidance on managing B2B software in production covers your ongoing obligations, including notifying changes and maintaining conformance across versions.

Common rejection reasons and gotchas

This is where integration schedules actually die. The recurring ones:

The Validator passed but the gateway rejected the upload. The Clinical Package Validator checks document structure, not runtime state. IHI currency, HPI-I validity, access sessions, and metadata consistency are only checked at the gateway. Local validation is necessary, never sufficient.
Stale or unverified IHIs. The IHI in an uploaded document must have been validated against the HI Service, and IHIs can change status (merged, retired, resolved). Uploading with an IHI your system verified months ago and cached is a classic rejection. Re-validate on a sensible currency window, and handle the HI Service's 'do not use' outcomes explicitly.
Certificate and HPI-O mismatches. The NASH certificate used to sign the request must belong to the HPI-O asserted in the PCEHR header. Mixing SVT and production certificates, or presenting a client organisation's HPI-O while signing with your own certificate outside an approved CSP arrangement, both fail — sometimes with unhelpfully generic errors.
Skipping gainPCEHRAccess. Document operations without a current access session fail with access-denied responses, as do records protected by an access code your workflow never prompts for. Build the access-code path in from the start; it's a NoC test case anyway.
Broken supersede chains. Replacing a document means uploading a new version that correctly references the document it supersedes. Getting set IDs and version handling wrong either duplicates documents in the patient's record or triggers rejection. Decide your document identity strategy before your first upload, not after your first correction.
Signature and approver problems. The package signature must verify against the uploading organisation's NASH credential, and the approver details inside the CDA must line up with the identifiers in the message. Copy-pasted sample values from test code have shipped to production more than once.
Metadata that contradicts the document. Document type and class codes in the submission metadata must agree with the CDA template used. A Shared Health Summary uploaded with mismatched type codes is rejected even when the document itself is valid.
Clock drift. WS-Security timestamps are checked. A server a few minutes off NTP produces intermittent, maddening authentication failures that look like certificate problems.
Treating SVT success as done. SVT data is clean. Production has restricted records, access codes, superseded IHIs, and patients without records. If your error handling was only ever exercised against happy-path test patients, your support queue will find the gaps for you.

Building a My Health Record integration? CareForge scopes and builds ADHA-conformant integrations — CDA authoring, B2B Gateway plumbing, and taking your product through NoC and the vendor declaration. Book an intro call if you want an experienced hand on it.

Last reviewed: July 2026