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 0.3.0-preview built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/AuDigitalHealth/HealthConnect/ and changes regularly. See the Directory of published versions

Search Parameters

Page standards status: Informative

Overview

The search parameters defined in this implementation guide specify the recommended approaches for client systems to query the Health Connect Provider Directory system and are the authoritative specification for discovering and retrieving healthcare Provider Directory data. Client systems integrating with Health Connect SHOULD use these search parameters to ensure consistent and reliable data retrieval across all client integrations.

The Health Connect Provider Directory supports all search parameters defined in this implementation guide, plus inherited FHIR search capabilities from the derived profiles. All search parameters are marked as SHOULD support for the Health Connect Provider Directory Requester Actor, allowing implementers flexibility in choosing which parameters to support based on their specific use cases and integration requirements. Client systems can utilise any of the available search parameters, and should conform to the specifications and constraints defined herein where applicable to their use case.

Useful standard search parameters for this IG

_lastUpdated: Enables querying resources based on when they were last modified in the Health Connect Provider Directory. This parameter is particularly useful for synchronization scenarios where client systems need to identify resources that have changed since a specific point in time. The parameter supports comparison prefixes to enable flexible date range queries:

  • gt (greater than): Returns resources updated after the specified date/time
  • lt (less than): Returns resources updated before the specified date/time
  • ge (greater than or equal): Returns resources updated on or after the specified date/time
  • le (less than or equal): Returns resources updated on or before the specified date/time

The date/time value can be specified with varying precision (year, month, day, hour, minute, second). Time components are optional - if omitted, the system assumes the start or end of the period as appropriate for the comparison.

Example usage for type-specific search:

GET [base]/Practitioner?_lastUpdated=gt2025-01-01T00:00:00Z

This query retrieves only Practitioner resources updated since January 1, 2025.

_elements: Controls which elements are returned in the response by accepting a comma-separated list of element names. When specified, the server returns only the requested elements. This reduces bandwidth usage and improves query performance by limiting response payload size.

Example usage:

GET [base]/Practitioner?_elements=identifier,active

This query retrieves Practitioner resources but returns only the identifier and active elements (plus mandatory FHIR elements).

Relationship traversal

_include and _revinclude: Enables including related resources in a single response by traversing resource relationships. _include follows references from primary search results to related resources, while _revinclude finds resources that reference the primary search results. Multiple parameters can be combined to traverse complex relationships across profile boundaries.

Examples:

GET [base]/PractitionerRole?_include=PractitionerRole:practitioner&_include=PractitionerRole:organization

Retrieves PractitionerRole resources with their associated Practitioner and Organization resources.

GET [base]/HealthcareService?_revinclude=PractitionerRole:service&_include=PractitionerRole:practitioner

Retrieves HealthcareService resources, plus PractitionerRole resources that reference those services, plus the Practitioner resources referenced by those PractitionerRole instances.

GET [base]/PractitionerRole?_lastUpdated=gt2025-01-01&_include=PractitionerRole:practitioner&_include=PractitionerRole:organization

Combines relationship traversal with date filtering to retrieve updated PractitionerRole resources and their related resources.

The appropriate combination of parameters depends on the referencing hierarchy defined in the profiles. Client systems should consult the profile structure (illustrated by the diagram found on the index page) and profile narrative sections to determine the correct traversal path for their use case.

Pagination

The Health Connect Provider Directory supports paginated search results. The Provider Directory has a default page size of 10 resources. The _count parameter is supported generically by the service; clients may include _count to express a preferred page size.

  • Follow the next link: When a search response is paginated, the server returns a Bundle that may include a link entry with relation="next". Clients SHOULD use the next link to retrieve subsequent pages rather than reconstructing paging URLs.

Example:

GET [base]/HealthcareService?_count=50

This request expresses a preference for up to 50 resources per page; the server may honour this preference or return a different page size. If there are more results, the returned Bundle may include a link element with relation="next" for fetching the next page.

Custom IG-defined Search Parameters

This section lists the custom SearchParameters that have been defined within this Implementation Guide.

Name Description
All Day Search HealthcareServices or PractitionerRoles by whether they are available all day.
End Time Search HealthcareServices or PractitionerRoles by availability end time.
Start Time Search HealthcareServices or PractitionerRoles by availability start time.
Days of Week Search HealthcareServices or PractitionerRoles by days of week availability. Supports multiple days using OR logic.
Endpoint Payload Mime Type Search for Endpoint resources by payloadMimeType.
Endpoint URL Search for Endpoint resources by address (URL).
HC Endpoint Identifier Search an Endpoint record by its HC identifier.
Healthcare Service Billing Search for HealthcareService resources by billing information.
Languages Search HealthcareServices or PractitionerRoles by supported languages/communication methods. Shared across HealthcareService and PractitionerRole.
Location Amenities Search for Location resources by amenities.
Location Physical Type Search for Location resources by physicalType field.
Location Postal Address Search for Location resources by postal address components.
Practitioner's Registered Profession Search a Practitioner record by their registered profession using string values.
Practitioner's Recorded Sex or Gender Search a Practitioner record by their recorded sex or gender.
Practitioner Identifier (R5) Search a Practitioner record by any identifier, including HPI-I and Professional Registration Number (PRN), mimicks R5-style identifier searching. Supports both Practitioner.identifier and Practitioner.qualification.identifier.
Search Modifiers

The Health Connect Provider Directory supports specific search modifiers for string-type search parameters to tailor search functionality:

  • :exact - Performs case-sensitive, exact matching without partial matching. Use this when you need precise lookups with string-type parameters.
  • :contains - Searches for the value anywhere within the string, not just at the beginning. Use this for broader text searches.
  • :iterate - As a modifier to _include and _revinclude enables recursive traversal of reference chains in search results. In this IG, the primary use case for this would be following the Organization.partOf hierarchy to also retrieve all referenced parent organizations in a single query.

Note: Token-type search parameters (such as hcepi) provide exact matching by default and do not require modifiers.

String-Type Parameters with Modifier Support

The following string-type search parameters can be used with the appropriate modifier:

Parameter Resource Types Type Use Case for :exact Use Case for :contains
name (R4) Practitioner string Exact name match (case-sensitive) Recommended: Search for practitioners by partial name matches
regprof Practitioner string Exact profession match (case-sensitive) Recommended: Search for partial profession matches
locmailaddress Location string Not supported Search postal address components
name (R4) Location string Recommended: Partial name/alias search on Locations
Prefix Operators for Time Availability Searches

The Start Time and End Time search parameters support numeric prefix operators, allowing you to search for times before, after, or at a specific value. These parameters use a four-digit numeric format (HHMM, e.g., 0830 for 8:30am, 1700 for 5:00pm).

You can use the following prefixes to control the comparison:

Prefix Meaning Example Description
eq Equal eq0830 Matches exactly 08:30am
ne Not equal ne1700 Matches any time except 5:00pm
gt Greater than gt0900 Matches times after 9:00am
lt Less than lt1200 Matches times before 12:00pm (noon)
ge Greater than or equal ge0800 Matches times at or after 8:00am
le Less than or equal le1700 Matches times at or before 5:00pm

For example, to find HealthcareServices available after 9:00am, search with starttime=gt0900.