Skip to main content
The haau3 Scheduling API is a Slot Aggregator for SMART Scheduling Links (SSL). It ingests provider availability from many SSL publishers and serves it through one key-authenticated API. A Slot Discovery Client can search every publisher by calling the Scheduling API, instead of integrating with each publisher separately. SMART Scheduling Links is an HL7 specification for publishing open appointment availability. A publisher exposes a $bulk-publish manifest that points at NDJSON files of FHIR resources: Schedule, Slot, and the actors they reference (Location, Practitioner, PractitionerRole, HealthcareService). Anyone can poll the manifest to see what’s bookable and send patients to the publisher’s booking link.

​
The roles in SSL

The IG defines a small set of actors:
  • Slot Publisher: a healthcare provider’s API that advertises its available slots.
  • Provider Booking Portal: the provider’s UI where a patient books a slot.
  • Slot Aggregator: a third-party API that combines data from multiple Slot Publishers and offers unified search across them. It does not own the underlying data.
  • Slot Discovery Client: the patient’s booking tool. It searches for slots and sends the patient to the right portal to finish booking.
The haau3 Scheduling API is a Slot Aggregator. A Slot Discovery Client queries it once and gets consistent results across every publisher the API ingests, rather than polling and reconciling each publisher’s $bulk-publish feed itself. haau3 also operates a reference Slot Publisher — its own openly fetchable $bulk-publish feed — so you can test a direct publisher connection while evaluating the aggregator. It’s a contribution to the open standard, not a separate product. See Slot Publisher.

​
What the Scheduling API does as the aggregator

The Scheduling API turns raw publisher feeds into one queryable model in three steps:
  • Ingest: each publisher’s latest $bulk-publish snapshot is downloaded and tracked.
  • Validate: every resource is checked for base FHIR R4 validity, then against the SSL profiles with strict referential integrity. Records that don’t conform are quarantined and kept out of the served data.
  • Normalize: conforming slots are flattened into a denormalized Slot shape with its source publisher, status, start and end times, service type, an expanded location (name, telecom, address), provider, and isVirtual. Fields a source omits stay absent; the API adds nothing.
Quarantine keeps bad data out of the API, but the haau3 team also works directly with publishers to flag nonconformant slots so issues get fixed at the source. This keeps the served data at a consistently high quality over time.

​
Querying availability

Four endpoints serve the model. See the API Reference for full details.
  • GET /v1/scheduling/slots: search availability with filters (status, publisher, service type, city, state, virtual, time window, accepting-patients) and pagination. Every slot carries its source publisher, and publisher=<slug> narrows results to one publisher (useful for a publisher inspecting just its own slots). The acceptingPatients filter (HL7 accepting-patients codes — newpt / existptonly / existptfam) is lenient: a slot that does not declare an acceptance code still matches any requested value (absence never hides a slot), while a slot that declares one must equal it. A slot a source marks nopt (not accepting patients) is never served — it isn’t real availability — so it never appears in results regardless of the filter.
  • GET /v1/scheduling/actors: the providers and locations behind the slots, aggregated server side, with exact counts and soonest availability over the full match set. Paginated by card.
  • GET /v1/scheduling/publishers: list the registered publishers, each with an enabled flag (the slug values accepted by the publisher filter). A publisher can be listed and not currently ingesting, so check enabled rather than assuming every slug returns slots.
  • GET /v1/scheduling/service-types: list the distinct service types observed across served slots, each with a count — a discovery aid for the serviceTypeCode filter (the values it accepts), self-healing as publishers change.
All four require a valid API key (see Authentication). For your first call, start with the Quickstart.

​
Standards status

SMART Scheduling Links builds on FHIR Bulk Publish, the mechanism for distributing static, pre-generated FHIR datasets (provider directories, formularies, scheduling, and similar) through a $bulk-publish manifest. Bulk Publish is still being standardized. It lives in a working branch of the HL7 Bulk Data Access IG (see the Publish operation working draft) and is not yet an authorized publication. The Scheduling API builds on the current drafts. As Bulk Publish and SMART Scheduling Links are finalized, it will follow the published specifications, and the underlying conformance will firm up as those standards mature.