Developer guide · API v1

mhrConnect® API

A focused REST interface for Healthcare Identifier searches and core My Health Record access, retrieval and upload workflows.

Environment and implementation resources
Your HITORI integration contact will provide separate base URLs and credentials for each environment. Every API request should use HTTPS. A Postman collection and further detailed documentation are also provided when the middleware is provisioned in your cloud environment.

Endpoint summary

Method	Path	Purpose
POST	`/api/IHI`	Find an IHI
POST	`/api/provider/validate`	Validate HPI-I or HPI-O
POST	`/mhr/patient/verify`	Check record status
POST	`/mhr/access/validate`	Validate or gain access
GET	`/mhr/documents`	List documents
GET	`/mhr/documents/{documentId}/view`	View parsed CDA
POST	`/mhr/documents/upload`	Create and upload a document

Authentication

All endpoints require a JWT bearer token. Send the token in the Authorization header.

Authorization: Bearer YOUR_JWT

Tokens are validated for issuer, audience, lifetime and signature. Keep credentials server-side and never embed them in browser or mobile application source.

Error handling

Validation failures return a 400 response. Unexpected middleware or upstream failures return a 500 response. Some access decisions return 200 with access_granted: false, allowing the calling product to guide the user through access-code or consent steps.

IHI lookup

POST/api/IHI

Search using an IHI, Medicare number, DVA number, or electronic communication detail. Provide one identifier mode plus the demographic fields required for matching.

Example: Medicare lookup

curl "$BASE_URL/api/IHI" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "medicareCardNumber": "••••••••••",
    "medicareIRN": "1",
    "givenName": "Taylor",
    "familyName": "Nguyen",
    "dateOfBirth": "1985-06-12",
    "sex": "Female",
    "hpii": "800361••••••••",
    "hpio": "800362••••••••",
    "localUserId": "clinician-42"
  }'

Search field	Use
`ihiNumber`	Direct IHI lookup; checksum validated before the service call
`medicareCardNumber` + `medicareIRN`	Medicare search
`dvaFileNumber`	DVA search
`electronicCommunication`	Email when it contains @; otherwise mobile

Response

{
  "IHINumber": "800360••••••••",
  "IHIStatus": "Active",
  "RecordStatus": "Verified"
}

Provider validation

POST/api/provider/validate

Validate either an individual provider identifier (HPI-I) or organisation identifier (HPI-O) against the HI Provider Directory.

{ "hpiiNumber": "800361••••••••" }

{
  "Type": "HPII",
  "Valid": true,
  "HpiiNumber": "800361••••••••",
  "Status": "MedicalPractitioner"
}

Patient verification

POST/mhr/patient/verify

Check whether a patient has a My Health Record and whether access restrictions apply.

{
  "family_name": "Nguyen",
  "given_name": "Taylor",
  "date_of_birth": "1985-06-12",
  "sex": "Female",
  "ihi_number": "800360••••••••"
}

The response includes ihi, mhr_status (ACTIVE, RESTRICTED, or OPTED_OUT) and access_restrictions.

Access validation

POST/mhr/access/validate

Check access and perform the gain-access step where permitted.

{
  "ihi": "800360••••••••",
  "purpose": "Clinical care",
  "consent_confirmed": true,
  "emergency_access": false
}

Field	Notes
`purpose`	Required free-text reason for access
`access_code`	Supply when the record is restricted
`consent_confirmed`	Must be true unless emergency access is used
`emergency_access`	Requests emergency access when true

Documents

GET/mhr/documents?ihi={ihi}&type={type}

List document metadata for a patient. The optional type filter uses the document type display name.

{
  "documents": [{
    "document_id": "…",
    "repository_unique_id": "…",
    "type": "Pathology Report",
    "author": "…",
    "organisation": "…",
    "date": "2026-07-19T14:30:00"
  }]
}

Retrieve a document

Path	Returns
`/mhr/documents/{documentId}`	Full CDA package as `application/zip`
`/mhr/documents/{documentId}/view`	Parsed metadata, sections, rendered HTML and attachment links
`/mhr/documents/{documentId}/pdf`	PDF attachment as `application/pdf`

Each retrieval route requires ihi. Include repository_unique_id unless it can be resolved from the middleware’s document-list cache.

Document upload

POST/mhr/documents/upload

Build and upload a PDF-backed clinical document. Send multipart/form-data. Use ?download_package=true to receive the generated CDA ZIP without uploading.

curl "$BASE_URL/mhr/documents/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@event-summary.pdf;type=application/pdf" \
  -F "document_type=EVENT_SUMMARY" \
  -F "ihi=800360••••••••" \
  -F "title=Consultation event summary" \
  -F "patient_given_name=Taylor" \
  -F "patient_family_name=Nguyen" \
  -F "author_hpii=800361••••••••" \
  -F "organisation_hpio=800362••••••••" \
  -F 'event_summary_json={"eventType":"General consultation","clinicalSynopsis":"…"}'

Required fields

Field	Notes
`file`	A PDF whose content starts with the PDF signature
`document_type`	One of the supported canonical values below
`ihi`	Patient IHI

Consent: if patient_consent_withheld=true, the upload is rejected.

Supported document types

document_type	Clinical document	Structured field
`EVENT_SUMMARY`	Event Summary Report 3A	`event_summary_json` (optional)
`SPECIALIST_LETTER`	Specialist Letter 3A	Standard form fields + PDF
`PATHOLOGY_REPORT`	Pathology Report	`pathology_json` (required)
`REFERRAL_LETTER`	e-Referral	`referral_json` (required)
`PRESCRIPTION_RECORD`	eHealth Prescription Record	`medication_json` (required)

Event summary JSON

Supports event type and date, reason for encounter, clinical synopsis, diagnoses, findings, interventions, medications, allergies, follow-up instructions and additional information.

Prescription record JSON

At minimum, include amtCode and medicationName. The schema also supports directions, dosage, route, frequency, quantity, repeats, prescription dates, prescriber details and item identifiers.

Need complete schemas, environment credentials or conformance support? Contact support@hitori-inc.com.