HCHB FHIR API — Use Case Library

This repository contains vetted Python use cases for integrating with the HCHB FHIR R4 API. It is maintained by Healing Hands Healthcare and made available to authorized vendors and integration partners.

Each use case demonstrates a specific data retrieval pattern using the HCHB FHIR API, with working, runnable code and JSON output.

Getting Started

Prerequisites

• Python 3.8+
• Access credentials for the HCHB FHIR API (provided by Healing Hands Healthcare)

Setup

1. Create and activate a virtual environment:

   python -m venv venv
   
   # Windows
   venv\Scripts\activate
   
   # macOS/Linux
   source venv/bin/activate

2. Install dependencies:

   pip install -r requirements.txt

3. Copy .env.example to .env and fill in your credentials:

   HCHB_CLIENT_ID=
   HCHB_RESOURCE_SECURITY_ID=
   HCHB_AGENCY_SECRET=
   HCHB_TOKEN_URL=
   HCHB_API_BASE_URL=
   

Use Cases

Get Patient's Current Team

Retrieves the care team assigned to a patient's most recent active episode.

Resource flow: Patient → EpisodeOfCare → branch-team-affiliation (extension) → Organization

# Run against 2 sample active patients
python use_cases/get_patient_team.py

# Run for a specific patient
python use_cases/get_patient_team.py --patient_id <patient_fhir_id>

Output is exported to use_cases/output/ as a JSON file.

Documentation

Reference documentation for the FHIR resources used across all use cases:

Resource	Description
Patient	Patient demographics and identifiers
EpisodeOfCare	Home health episodes and team assignment
Organization	Agencies, teams, branches, and payors
Account	Patient financial accounts and payor references

Project Structure

HCHB_FHIR/
├── documentation/
│   ├── Patient.md             # Patient resource reference
│   ├── EpisodeOfCare.md       # EpisodeOfCare resource reference
│   ├── Organization.md        # Organization resource reference
│   └── Account.md             # Account resource reference
├── use_cases/
│   ├── patients.py            # FHIR Patient resource wrapper
│   ├── output/                # JSON output files (gitignored)
│   └── get_patient_team.py    # Get the care team for a patient
├── .env                       # Credentials (not tracked)
├── .env.example
├── .gitignore
├── LICENSE
├── README.md
└── requirements.txt

Authentication

All requests authenticate using the HCHB OAuth2 agency_auth grant:

POST https://idp.hchb.com/connect/token
  grant_type=agency_auth
  client_id={HCHB_CLIENT_ID}
  resource_security_id={HCHB_RESOURCE_SECURITY_ID}
  agency_secret={HCHB_AGENCY_SECRET}
  scope=openid HCHB.api.scope agency.identity hchb.identity

Tokens are managed automatically and refreshed as needed.

Disclaimer

No EPHI (Electronic Protected Health Information) is stored or maintained in this repository. This repository is for integration reference only. All use cases are intended to support interoperability in service of optimizing patient care.

License

See LICENSE for details.