# Health Connect Australia Provider Directory FHIR Implementation Guide

26.0.0 - Trial

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

## Search Parameters

### 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`.