Developers
AusHealthPages shares its listings with other systems through a REST API, a FHIR R4 server and a change feed. Without credentials you see what the public sees; partners with an agreement may see more.
REST API
Search and read services, locations, organisations and practitioners as JSON. Without credentials you can make 60 requests a minute and 10,000 a day from one address.
https://api.hark.health/v1/d/aushealthpagesOpenAPI document (every request and response) (opens in a new tab)
FHIR R4 server
Read and search Organization, Location, HealthcareService, Practitioner, PractitionerRole and Endpoint resources in FHIR 4.0.1, as JSON. The server is read only.
https://api.hark.health/v1/d/aushealthpages/fhirCapabilityStatement (what the server supports) (opens in a new tab)
Resources claim these profiles (hl7.fhir.au.base#6.0.0):
- Organization: http://hl7.org.au/fhir/StructureDefinition/au-organization
- Location: http://hl7.org.au/fhir/StructureDefinition/au-location
- HealthcareService: http://hl7.org.au/fhir/StructureDefinition/au-healthcareservice
- Practitioner: http://hl7.org.au/fhir/StructureDefinition/au-practitioner
- PractitionerRole: http://hl7.org.au/fhir/StructureDefinition/au-practitionerrole
Change feed and webhooks
Partners keep a copy up to date by following the change feed, or by having changes sent to their own system as signed webhooks. Both need partner credentials.
https://api.hark.health/v1/d/aushealthpages/changesGet API access
Sign up for a developer account and you get sandbox credentials straight away. Then ask AusHealthPages for access from the developer console: its team decides what your organisation can read.
Sandbox credentials work in Highlands Health Finder at once, with its demo data and a low request limit.
Sign up for API accessOpen the developer console
One set of credentials works in every directory that gives your organisation access. Ask for a token for one directory at a time:
curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials -d directory=aushealthpages \
https://api.hark.health/oauth/tokenA directory may narrow your access to some areas, service categories or record types. Anything outside answers as a missing record everywhere: lists, search, the change feed, webhooks, FHIR and exports.
What a partner client may be allowed to do
- search:read
- Search services and autocomplete
- graph:read
- Read organisations, locations, services, practitioners and roles, including filtered lists
- feed:read
- Read the change feed
- export:run
- Request and download exports
- webhooks:manage
- Register webhook endpoints that receive the change feed (needs feed:read too)
- practitioners:read
- List practitioners and read their profiles, with the privacy rules applied (only what each practitioner shows to the client's tier). Granted only when a directory admin explicitly allows it; never implied by another scope (D-599)
- leadership:read
- Receive organisations' executives and board members (senior management) in the API, FHIR and exports, with only the details each person shows to health professionals. Granted only when a directory admin explicitly allows it; never implied by another scope, never in the sandbox (D-620)
Questions about access? To ask for access, contact AusHealthPages through its About page.
API changes
Changes to requests and responses, newest first. The OpenAPI document lists them too.
A directory's own categories made of local types now find exactly the services the directory tags with those local types, not every service of the platform type they refine, in search (category=), the category list and category pages; their counts agree. In GET /v1/d/{dir}/categories, a category's types may include the directory's local types, marked filter: "category" (search them with category=<code>); platform types have filter: "type" or no filter. Directories that tag no services with local types are unchanged.
Every phone-like value (contacts of kind phone, mobile, freecall, local_rate, fax, sms and tty on organisations, locations, services and practitioner roles; practitioners' own contacts; senior management phones; restricted contacts in partner exports) is a valid E.164 number of its own country, in the API, FHIR telecom, the change feed, webhooks and exports. Australian 13, 1300 and 1800 numbers, which were national digits (1800123456, 131114), are now E.164 too (+611800123456, +61131114), and numbers read before as Australian or New Zealand in other countries' directories are corrected; such records publish a new version once. A number may belong to another country than the directory's. Show a number in its national form when its country is yours and in the international form otherwise; dial it as given.
Practitioners may carry their own contacts, not at a workplace: contacts ([{kind: mobile, email or phone, value}], numbers in E.164) on practitioners (view=brief, the practitioner list, exports, the change feed and webhooks), as FHIR Practitioner.telecom, and on the practitioner page (view=page, with restricted: true for one not shown to everyone). Each appears only when the practitioner or the directory shows it to the caller's audience; they are staff only by default, so most practitioners carry none, and the key is left out when none is shown. Practitioners in bulk still need practitioners:read. Workplace contacts stay on each PractitionerRole as before. Additive: no field changed or left.
Senior management is switched on per directory: a platform operator makes it available and the directory admin switches it on, both off by default. While it is off, GET /v1/d/{dir}/organisations/{publicId}/leadership answers 404 (not-found-or-hidden), and organisations (view=brief), FHIR Organization.contact and exports carry no leadership, even for a client holding leadership:read. The people are kept and come back when it is switched on again. Nothing else changes.
Senior management. A new scope, leadership:read, which a directory grants only by an explicit choice (never implied, never in the sandbox), opens GET /v1/d/{dir}/organisations/{publicId}/leadership (current executives, then the board) and adds leadership to organisations (view=brief), to FHIR Organization.contact and to JSON and FHIR exports. Each person shows only what they show to health professionals: never a staff-only detail or a past appointment, and never in the change feed or webhooks. For everyone, organisations add postalAddress and metroRural (metro or rural, set by hand or derived from the remoteness area) when known, and the organisation page adds lastUpdated. Additive: no field changed or left.
The organisation page adds locations: every site of the organisation the caller may see, each with publicId, name, area, address (display lines, or null when the address is withheld), addressWithheld, point (null when withheld), openStatus (the best open state of its services now, with detail) and its services (publicId, slug, name, typeDisplay, categoryIcon). Unlisted sites never appear to public callers. Additive: no field changed or left.
Organisations, locations and services say who runs them: ownershipType (code and display: public, private, not_for_profit or another type, or the directory's own {directory}:{code}) and ownershipSource (service, location or organisation: where it was set, as a service inherits its location's type and a location its organisation's). Both are left out when a record has none. Search takes ownership (codes separated by commas) and answers an ownership facet; search cards and service listings add ownership (code, label and source). FHIR Organization, Location and HealthcareService carry the ownership-type extension, and the services CSV export adds the columns ownershipType and ownershipSource at the end. Additive: no field changed or left.
Categories and service types carry an icon: a design system icon name (for example stethoscope or glasses) to show beside the name, never alone. Added to each category of GET /v1/d/{dir}/categories and /categories/{code} (icon), to each category, local type and platform type of GET /v1/d/{dir}/taxonomy (icon), and to each search result card of GET /v1/d/{dir}/search/services, the services of a collection and service listings (categoryIcon, the icon for the service's type, with categoryCode, the platform category of its type, or null). Each type and category has a platform default that operators may change, and a directory may choose its own for its types and categories; anything else is briefcase-medical. Additive: no field changed or left.
Exports are written in parts, so very large exports finish; their records and order are unchanged. The JSON export file is no longer indented: one line of JSON with the same content. The CSV and FHIR files are unchanged. Category counts carry their own cache tag (cat: and the directory's name in its address) instead of the search tag, purged when a listing enters, leaves or changes type. The service list and exports leave out a listing under a takedown from the moment it is taken down.
Responses are compressed and kept longer by shared caches; bodies are unchanged. Text answers of 1 KB or more come compressed with Brotli or gzip when the request accepts it (Accept-Encoding, with Vary: Accept-Encoding). Anonymous public reads now say how long shared caches may keep them, with cache tags: autocomplete (public, max-age=60, s-maxage=300), location and organisation pages and the service list without a client (s-maxage=60) and the sitemap (s-maxage=300); the taxonomy adds a cache tag. Published images add immutable and an ETag (the content hash) and answer 304 to a matching If-None-Match. Answers for professionals, partners and narrowed clients stay private, no-store.
Behaviour change: practitioners in bulk are one choice. A partner client without practitioners:read gets no practitioners from exports, the change feed, webhooks or FHIR _include; roles stay, naming their practitioner by public ID, and reading one practitioner is unchanged. Without a client, FHIR Practitioner search answers 403 and the feed leaves practitioners out unless the directory lets anyone list practitioners (a new setting, off by default); then the practitioner list works without a client too.
New scope practitioners:read and a new list, GET /v1/d/{dir}/practitioners: practitioners with an active role at a service you can see, each with only what they show to your tier, inside your narrowing. A directory grants it only by an explicit choice; the sandbox does not have it. Without it the list and a FHIR Practitioner search answer 403 forbidden-scope. Access requests take practitionerListReason.
Partner organisations' credentials (client_id hsdp_...) from the developer console work in every directory that gave the organisation access: the token request takes directory, the directory's slug, and the token response adds directory and sandbox. Directory clients (hsdc_...) work as before.
Any client may be narrowed by the directory to some areas, service categories or record types (before, aggregate directories only). Records outside answer 404 not-found-or-hidden and are left out of lists, search, the change feed, webhooks, FHIR and exports. DeveloperInfo adds developerPortal.
Practitioner gender is now one of woman, man, non_binary, different_term or prefer_not_to_say (it was free text), with an optional genderOwnTerm, the practitioner's own term, only with different_term. Public callers never receive prefer_not_to_say.