Health Connect Australia Provider Directory FHIR Implementation Guide

Health Connect Australia Provider Directory FHIR Implementation Guide, published by Australian Digital Health Agency. This guide is not an authorized publication; it is the continuous build for version 26.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/AuDigitalHealth/HCPD/ and changes regularly. See the Directory of published versions

Health Connect Provider Directory API Overview

Overview

The Health Connect Australia Provider Directory (the Directory) API gives FHIR-based access to provider and organisation directory data. Clients can search it, read individual records, and export in bulk.

This API is the national implementation of the Health Connect Australia Provider Directory FHIR Implementation Guide.

This specification defines how clients interact with the APIs in practice, focusing on supported operations, validation rules, and operational requirements for integration. The Health Connect Australia Provider Directory FHIR IG remains the normative source of truth for resource structure and semantics.

Detailed behaviour for each capability is described on its own page:

• Search API technical specification - real-time search and read behaviour. Use the Search API for targeted, real-time queries and interactive lookups.
• Export API technical specification - asynchronous bulk data export behaviour. Use the Export API for large-scale extracts and local data synchronisation.

API features and capabilities

The public API does two things: real-time search and read, and asynchronous bulk export.

Search locates practitioners, organisations, services and the resources linked to them, using standard FHIR search parameters with paging and filtering.

Export returns large datasets asynchronously through the FHIR Bulk Data Access $export pattern, for clients keeping a local copy of the directory.

Supported resources

The public API provides access to the following FHIR resources:

• Organization
• Practitioner
• PractitionerRole
• HealthcareService
• Location
• Endpoint
• Provenance

All resources conform to Health Connect Australia Provider Directory FHIR profiles, including constraints on structure, cardinality, search parameters, and terminology. For the profiles, extensions, search parameters and terminology that apply to each resource type, see the Implementation Guide home page.

Elements not supported by the service

The API will not store or return the following Practitioner elements. This differs from the FHIR IG, which permits them.

A create or update carrying one of these elements still succeeds; the element is stripped before the resource is persisted and is never present in a read or search response. A rejected search parameter is rejected in a forward or reverse chain too. See Restricted search parameters.

Use rsg in place of gender and gender identity. See the Practitioner's Recorded Sex or Gender search parameter.

The PBS prescriber number is identified by the system http://ns.electronichealth.net.au/id/medicare-prescriber-number.

Environments and base URLs

Environment access is arranged as part of client onboarding.

Endpoint path convention

All examples in these API pages are path-only and are relative to the environment base URL above.

Example:

• Full URL: https://healthconnect.digitalhealth.gov.au/api/v1/fhir/Organization?name=clinic
• Path-only form used in examples: /Organization?name=clinic

Authentication and authorisation

All API requests must include a valid OAuth2 bearer token (JWT) issued by the Health Connect Authorisation Service (HCAS), presented as Authorization: Bearer <jwt>.

Required scopes by operation

Clients are not required to present all scopes on every request. The required scope is operation-specific:

Presenting a token without the scope required for an operation results in 403 Forbidden.

Authentication example:

GET /Organization?identifier=8003626566707032
Authorization: Bearer <jwt>
X-Request-ID: 6f0d0f2e-3e42-4a43-986a-a4ecba0ab7e4
Accept: application/fhir+json

Client registration and token issuance

To be updated.

Registration, token issuance, token lifetime and renewal, and authorisation error conditions are covered in a separate HCAS document. This page will link to it once it is published.

Record status

A record is either active or inactive. Practitioner, PractitionerRole, Organization and HealthcareService carry a boolean active; Location and Endpoint carry status.

Search returns active records by default. Inactive records are returned only when the state is asked for explicitly. See Data visibility rules for search for the permitted values on each type and how to request them.

Records may be suppressed by the upstream systems. Suppressed records are never returned in any search. Their status updates are included in incremental exports so that client systems can remove them locally. See Visibility rules for export.

Error handling

All errors are returned as a FHIR OperationOutcome. Every OperationOutcome also carries the request correlation identifier as an additional informational issue, so that a client-side failure can be correlated with server-side logs for traceability.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "some error message here"
    },
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "X-Request-ID: 9c63ec77-8d78-4bf1-a170-9909b33a786b"
    }
  ]
}

HTTP status mapping

Note that an empty search result is not an error. A search that matches nothing returns 200 OK with a Bundle of total: 0. See No matching records.

Rate limits

To be updated.

Request rate limits and per-client quotas returning 429 Too Many Requests, and the backoff behaviour expected of a client. One limit is already defined: export status polling is limited to one request per status endpoint every 120 seconds - see Polling and completion.

Glossary