healthcloud-sdk 0.7.0

Python SDK for HealthCloud APIs.

HealthCloud SDK for Python

Typed Python SDK for HealthCloud services and the HealthCloud Connectors gateway.

Installation

pip install healthcloud-sdk

For local development:

pip install -e ./packages/pip

Python 3.9 or newer is required.

Create and authenticate a client

The current API uses typed request objects. Authentication returns typed response objects; after registration or login, explicitly share the access token with the whole SDK by calling set_access_token.

from healthcloud import HCSDK, LoginRequest, RegisterPatientRequest

sdk = HCSDK(environment="dev", tenant_id="your-tenant-id")

registration = sdk.auth.register(RegisterPatientRequest(
    first_name="Jane",
    last_name="Doe",
    email="[e-mail]",
    password="SecurePassword123!",
    date_of_birth="1990-06-15",
    sex_at_birth="female",
))

token = registration.access_token
if not token:
    login = sdk.auth.login(LoginRequest(
        email="[e-mail]",
        password="SecurePassword123!",
    ))
    token = login.access_token

sdk.set_access_token(token)

In UAT and production, complete email verification before login when the register response reports that verification is required.

from healthcloud import VerifyOtpRequest

sdk.auth.verify_email(VerifyOtpRequest(
    user_id=registration.cognito_sub,
    otp="123456",
))

Service clients

One HCSDK instance exposes these clients:

sdk.auth
sdk.patient
sdk.vitals
sdk.diagnostics
sdk.assistant
sdk.communications
sdk.fieldagent
sdk.mcp
sdk.connectivity

# Service clients whose public SDK surface is currently connect-only:
sdk.appointments
sdk.ehr
sdk.provider
sdk.rppg
sdk.session
sdk.telehealth

All typed methods accept the request model shown in their signature and return a typed response model. Examples:

from healthcloud import SubmitVitalsRequest, UpdatePhoneRequest

patient = sdk.patient.get_patient("patient-id")

phone = sdk.patient.set_phone(
    "patient-id",
    UpdatePhoneRequest(phone="[phone]"),
)

vitals = sdk.vitals.submit(
    "patient-id",
    SubmitVitalsRequest(
        heart_rate=72,
        systolic=120,
        diastolic=80,
    ),
)

history = sdk.vitals.get_vitals("patient-id")
tools = sdk.mcp.list_tools("patient")

Use sdk.set_access_token(new_token) whenever a token changes. This updates every authenticated service client and every connector client on the SDK instance.

Connectors

Connector methods are called through sdk.connectors; they are not raw HTTP helpers. The package contains 33 connector clients.

Architecture

Connector clients are created in three explicit steps:

1. Configure HealthCloud once through HCSDK (environment, tenant, access token).
2. Create an isolated connector client with that connector's vendor credentials via sdk.connectors.<name>.create_client(...).
3. Call typed operation methods with operation-specific parameters only.

The connector gateway URL is resolved internally from the HealthCloud environment; applications never pass connector base URLs or the HealthCloud bearer token again when creating a connector client. Each client holds its vendor credentials only on that instance and forwards them to the HealthCloud Connectors gateway (POST /connectors/<slug>/<operation>) with every request. Connector-scoped secrets cannot be overridden by operation input, and gateway errors are redacted before being raised.

Create a credential-scoped connector client explicitly. The SDK never reads connector credentials implicitly; applications can load them from their own secret manager or the local .env used by integration tests. Do not hardcode credentials in source code and do not create connector clients in client-side code.

Usage

import os

from healthcloud import HCSDK

sdk = HCSDK(
    environment="dev",
    tenant_id="your-tenant-id",
    access_token="cognito-access-token",
)

athena = sdk.connectors.athena_health.create_client(
    secret_key=os.environ["HC_ATHENA_SECRET_KEY"],
    practice_id=os.environ["HC_ATHENA_PRACTICE_ID"],
    department_id=os.environ["HC_ATHENA_DEPARTMENT_ID"],
    provider_id=os.environ["HC_ATHENA_PROVIDER_ID"],
)
patients = athena.search_patients(
    last_name="Smith",
    limit=5,
)

stripe = sdk.connectors.stripe.create_client(api_key=os.environ["HC_STRIPE_API_KEY"])
stripe_status = stripe.verify_connection()

# Public connector — no vendor credentials required
nppes = sdk.connectors.nppes.create_client()
provider = nppes.verify_provider(npi="1234567890")

# OAuth-style connector
whoop = sdk.connectors.whoop.create_client(
    client_id=os.environ["HC_WHOOP_CLIENT_ID"],
    client_secret=os.environ["HC_WHOOP_CLIENT_SECRET"],
)

Pass mode="live" only when required; mode="sandbox" is the default for mode-aware connectors. Calling sdk.set_access_token(...) propagates the new HealthCloud token to every connector client already created.

Available connectors

The table lists each connector's required credential keyword arguments and the conventional HC_* environment variable names used by the live test suite (names only — never commit values). Parameters marked mode? accept "sandbox" (default) or "live".

Connector	Purpose	create_client credentials	Suggested env vars	Called via
anthropic	Anthropic (Claude) LLM completions	api_key, mode?	HC_ANTHROPIC_API_KEY	sdk.connectors.anthropic.create_client(...)
apple_auth	Sign in with Apple token exchange	team_id, client_id, key_id, redirect_uri, private_key	HC_APPLE_AUTH_TEAM_ID, HC_APPLE_AUTH_CLIENT_ID, HC_APPLE_AUTH_KEY_ID, HC_APPLE_AUTH_REDIRECT_URI, HC_APPLE_AUTH_PRIVATE_KEY	sdk.connectors.apple_auth.create_client(...)
athena_health	athenahealth EHR (patients, appointments)	secret_key, practice_id, department_id, provider_id, mode?	HC_ATHENA_SECRET_KEY, HC_ATHENA_PRACTICE_ID, HC_ATHENA_DEPARTMENT_ID, HC_ATHENA_PROVIDER_ID	sdk.connectors.athena_health.create_client(...)
cal	Cal.com scheduling and bookings	api_key	HC_CAL_API_KEY	sdk.connectors.cal.create_client(...)
carequality	Carequality health information exchange	api_key, initiator_url	HC_CAREQUALITY_API_KEY, HC_CAREQUALITY_INITIATOR_URL	sdk.connectors.carequality.create_client(...)
cms	CMS (Centers for Medicare & Medicaid) data	api_key	HC_CMS_API_KEY	sdk.connectors.cms.create_client(...)
connecture	ConnectureDRX Medicare plan shopping	basic_token, client_key, client_secret	HC_CONNECTURE_BASIC_TOKEN, HC_CONNECTURE_CLIENT_KEY, HC_CONNECTURE_CLIENT_SECRET	sdk.connectors.connecture.create_client(...)
elevenlabs	ElevenLabs text-to-speech	api_key	HC_ELEVENLABS_API_KEY	sdk.connectors.elevenlabs.create_client(...)
fedex	FedEx shipping and tracking	client_id, client_secret, account_number, mode?	HC_FEDEX_CLIENT_ID, HC_FEDEX_CLIENT_SECRET, HC_FEDEX_ACCOUNT_NUMBER	sdk.connectors.fedex.create_client(...)
google_ai	Google AI (Gemini) LLM	api_key	HC_GOOGLE_AI_API_KEY	sdk.connectors.google_ai.create_client(...)
google_places	Google Places search/geocoding	api_key, mode?	HC_GOOGLE_PLACES_API_KEY	sdk.connectors.google_places.create_client(...)
grok	xAI Grok LLM	api_key	HC_GROK_API_KEY	sdk.connectors.grok.create_client(...)
healthie	Healthie EHR / practice management	secret_key, mode?, shard_id?	HC_HEALTHIE_SECRET_KEY, HC_HEALTHIE_AUTHORIZATION_SHARD	sdk.connectors.healthie.create_client(...)
impilo	Impilo remote patient monitoring logistics	api_key	HC_IMPILO_API_KEY	sdk.connectors.impilo.create_client(...)
junction	Junction (Vital) lab testing and wearables	api_key	HC_JUNCTION_API_KEY	sdk.connectors.junction.create_client(...)
nppes	NPPES NPI registry lookup (public, no credentials)	—	—	sdk.connectors.nppes.create_client()
openai	OpenAI LLM completions	api_key	HC_OPENAI_API_KEY	sdk.connectors.openai.create_client(...)
oura	Oura ring wearable data (OAuth)	client_id, client_secret, mode?	HC_OURA_CLIENT_ID, HC_OURA_CLIENT_SECRET	sdk.connectors.oura.create_client(...)
plaid	Plaid identity / financial verification	client_id, secret, template_id, mode?	HC_PLAID_CLIENT_ID, HC_PLAID_SECRET, HC_PLAID_TEMPLATE_ID	sdk.connectors.plaid.create_client(...)
quest	Quest Diagnostics — REST-style orders/results/catalog and HL7 orders, results, compendium	client_id, client_secret, mode?	HC_QUEST_CLIENT_ID, HC_QUEST_CLIENT_SECRET	sdk.connectors.quest.create_client(...)
salesforce	Salesforce CRM records and queries	client_id, client_secret, username, password, mode?	HC_SALESFORCE_CLIENT_ID, HC_SALESFORCE_CLIENT_SECRET, HC_SALESFORCE_USERNAME, HC_SALESFORCE_PASSWORD	sdk.connectors.salesforce.create_client(...)
scrapfly	Scrapfly web scraping	api_key	HC_SCRAPFLY_API_KEY	sdk.connectors.scrapfly.create_client(...)
senaite	SENAITE LIMS (lab information management)	base_url, username, password	HC_SENAITE_BASE_URL, HC_SENAITE_USERNAME, HC_SENAITE_PASSWORD	sdk.connectors.senaite.create_client(...)
sendgrid	SendGrid transactional email	api_key, mode?	HC_SENDGRID_API_KEY	sdk.connectors.sendgrid.create_client(...)
steadymd	SteadyMD telehealth clinician network	api_key or token (exactly one), mode?, api_url?	HC_STEADYMD_API_KEY or HC_STEADYMD_TOKEN, HC_STEADYMD_API_URL	sdk.connectors.steadymd.create_client(...)
stedi	Stedi insurance eligibility (X12/EDI)	api_key	HC_STEDI_API_KEY	sdk.connectors.stedi.create_client(...)
stripe	Stripe payments and subscriptions	api_key	HC_STRIPE_API_KEY	sdk.connectors.stripe.create_client(...)
twilio	Twilio SMS / voice messaging	account_sid, auth_token, from_number, mode?	HC_TWILIO_ACCOUNT_SID, HC_TWILIO_AUTH_TOKEN, HC_TWILIO_FROM_NUMBER	sdk.connectors.twilio.create_client(...)
uber	Uber Direct / Health rides and deliveries	client_id, client_secret, customer_id, mode?	HC_UBER_CLIENT_ID, HC_UBER_CLIENT_SECRET, HC_UBER_CUSTOMER_ID	sdk.connectors.uber.create_client(...)
whoop	WHOOP wearable data (OAuth)	client_id, client_secret, mode?	HC_WHOOP_CLIENT_ID, HC_WHOOP_CLIENT_SECRET	sdk.connectors.whoop.create_client(...)
zocdoc	Zocdoc provider search and booking	api_key	HC_ZOCDOC_API_KEY	sdk.connectors.zocdoc.create_client(...)
zus	Zus Health aggregated patient data	client_id, client_secret, mode?	HC_ZUS_CLIENT_ID, HC_ZUS_CLIENT_SECRET	sdk.connectors.zus.create_client(...)

Note: the single quest connector covers both the REST-style order/results/catalog operations and the HL7 message-based operations, all routing to the gateway's quest slug with the same credentials.

Errors and cleanup

from healthcloud import HealthCloudHTTPError, HealthCloudNetworkError

try:
    stripe.verify_connection()
except HealthCloudHTTPError as exc:
    print(exc.status_code, str(exc))
except HealthCloudNetworkError as exc:
    print(str(exc))
finally:
    sdk.close()

Verification

From packages/pip:

.\.venv\Scripts\python.exe -m pytest -q -m "not live"

Live integration tests are opt-in and use package methods:

$env:HC_RUN_INTEGRATION="true"
$env:HC_ALLOW_REGISTER="true"
.\.venv\Scripts\python.exe -m pytest -q -m live

Do not commit .env files or connector credentials.