> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haau3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMART Scheduling Links

> How the haau3 Scheduling API aggregates provider availability from SMART Scheduling Links publishers.

The **haau3 Scheduling API** is a **Slot Aggregator** for
[SMART Scheduling Links](https://build.fhir.org/ig/HL7/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.

## What SMART Scheduling Links is

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](/scheduling/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`](/api-reference) 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](/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](/authentication)). For your first call,
start with the [Quickstart](/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](https://build.fhir.org/ig/HL7/bulk-data/en/) (see the
[Publish operation working draft](https://build.fhir.org/ig/HL7/bulk-data/branches/argo25/en/publish.html))
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.