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

# FHIR Overview

> Introduction to FHIR R4, US Core, and how Connective Health structures its FHIR outputs

# Basics

For customers interested in the structured dataset underpinning our product suite (Care Summary, Risk Adjustment, and Quality Gap Closure), Connective Health offers clinical data as FHIR resources. The dataset is deduplicated, normalized, and curated using best-in-class data cleansing.

Connective Health currently produces three distinct FHIR outputs:

* **[Patient Everything Bundle](/fhir/patient-everything-bundle)** -- the full clinical history assembled for a patient.
* **[Patient Summary Bundle](/fhir/patient-summary-bundle)** -- a curated, clinically-relevant subset of a patient's history.
* **[Bulk Medication History](/fhir/bulk-medication-history-bundle)** -- medication fill and prescription history for a population of patients, delivered as a set of [Bulk Data Access](https://build.fhir.org/ig/HL7/bulk-data/en/) newline-delimited JSON (NDJSON) files rather than a single Bundle.

The first two are produced automatically for a patient whenever a new set of clinical data finishes processing, and share the same resource types, field mappings, and ID rules -- they differ in *which* records they include. Bulk Medication History is produced in response to a patient population request and covers only medication data.

The curation approach is not one-size-fits-all -- instead, it is targeted and configurable. In cases where recency matters (e.g. encounters), there are time-based limits. In other cases (e.g. chronic diseases, medications), there are clinical rules to filter by relevance. In some cases, the dataset can stretch back more than twenty years -- but only if clinically relevant and "clean".

In the event that the source data does not satisfy FHIR or US Core profile validations, we will generally still send it, allowing the customer final control over whether to ingest, correct, or disregard the data.

# FHIR R4

All of Connective Health's FHIR interactions and resources are based on the [FHIR R4](https://www.hl7.org/fhir/R4/) specification, published by [HL7](https://www.hl7.org/). FHIR (Fast Healthcare Interoperability Resources) defines a common set of "resources" -- discrete units of clinical or administrative data such as `Patient`, `Condition`, or `MedicationRequest` -- along with rules for how they reference one another and are exchanged.

# US Core

Whenever possible, resources also implement the corresponding [US Core](https://hl7.org/fhir/us/core/STU9/index.html) profile (currently version **STU9**) and will pass its validations. US Core is a US-government-recognized implementation guide that narrows the broader FHIR R4 specification into a set of profiles tailored to US healthcare data exchange -- for example, requiring specific identifier types, terminologies, and minimum data elements for each resource type.

Each resource page in this section links to both the base FHIR R4 definition and the applicable US Core profile (when one exists) for that resource.

# Bundles

For the Patient Everything and Patient Summary outputs, the base element is a [Bundle](https://www.hl7.org/fhir/R4/bundle.html) resource containing every resource for a patient. Both are `collection` bundles -- see [Bundle Structure](/fhir/patient-everything-bundle#bundle-structure) for exactly which bundle-level fields are populated. The Bulk Medication History output does not use a single Bundle resource -- see its [dedicated page](/fhir/bulk-medication-history-bundle) for details on that format.

All information has been deduplicated, normalized, augmented, and curated before transforming into FHIR format.

## FHIR IDs

Whenever practical, the [FHIR ID](https://hl7.org/fhir/R4/resource-definitions.html#Resource.id) will remain stable across bundles. Each resource page in this section describes the specific fields ("ID Fields") used to determine whether a piece of clinical information has changed from one bundle to the next -- if none of those fields change, the resource is assigned the same ID again.

Mechanically, the ID is the resource type followed by a hash of those field values, for example `Condition-6f1b...`. Values are normalized (trimmed and case-folded) before hashing, so an incidental difference in whitespace or casing does not produce a new ID. Two consequences are worth calling out:

* **Content changes create a new resource rather than updating the old one.** Because the ID is derived from the clinical content, a corrected value yields a resource with a different ID -- not a new version of the same ID.
* **IDs double as the deduplication key.** Two source records carrying the same identifying values resolve to the same ID and collapse into a single bundle entry, so the same record reported by two contributing sources appears once.

## Contained resources

Not every resource is its own bundle entry. Provider, facility, and drug-product resources -- and each encounter's diagnosis -- are emitted [contained](https://www.hl7.org/fhir/R4/references.html#contained) inside the resource that references them. Contained resources have no ID, and so are neither stable nor deduplicated. See [Contained resources](/fhir/patient-everything-bundle#contained-resources).

## Terminology

Clinical codes are published as FHIR `Coding`s with a canonical `system` URI resolved from the source terminology. See [Code Systems](/fhir/code-systems) for the full mapping and for how code values are normalized.

# Delivery

Customers receive FHIR output pushed to cloud storage:

* S3 bucket (currently available)
* Azure (currently available)
* Google Cloud Storage (soon to be available)

A [webhook](/product/webhooks) notification (`document.deliveryComplete`) is sent once a document (PDF or FHIR bundle) has been successfully delivered. Webhook support for the Bulk Medication History output specifically is planned but not yet available.